feat(extensions): add willytop8.click-ripple cursor-effect example

EXTENSIONS.md

@@ -289,3 +289,4 @@ Use `parentSection` to nest your panel inside an existing area such as `cursor`
 ## Examples
 
 - `extension-examples/webadderall.more-wallpapers` shows a user-installable wallpaper bundle that registers 180 packaged wallpapers through `registerWallpaper()`.
+- `extension-examples/willytop8.click-ripple` shows a cursor-effect extension that renders animated ripple, pulse, and burst effects at every click using `registerCursorEffect()`.

extension-examples/willytop8.click-ripple/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+*.log
+.DS_Store

extension-examples/willytop8.click-ripple/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Vest
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

extension-examples/willytop8.click-ripple/README.md

@@ -0,0 +1,87 @@
+# Recordly Click Ripple
+
+Animated cursor click effects — ripple, pulse, or burst — rendered at every click. Visible in the editor preview and baked into the exported video.
+
+## Install
+
+### From the Recordly Marketplace
+
+Search for **Click Ripple** at [marketplace.recordly.dev/extensions](https://marketplace.recordly.dev/extensions) and click **Install**.
+
+### From a release zip
+
+1. Download the latest zip from the [Releases](https://github.com/willytop8/recordly-click-ripple/releases/latest) page.
+2. In Recordly, go to **Extensions → Open Directory**. Your file manager opens the user extensions folder.
+3. Unzip the archive into that folder so that a `recordly-click-ripple/` directory appears there with `recordly-extension.json` at its root.
+4. Restart Recordly.
+5. Open the Extensions panel and confirm **Click Ripple** shows as **active**.
+
+### From source
+
+```bash
+git clone https://github.com/willytop8/recordly-click-ripple
+cd recordly-click-ripple
+npm install
+npm run build
+```
+
+Copy the folder into Recordly's extensions directory (step 2 above) and restart.
+
+## Settings
+
+Configure under **Settings → Cursor → Click Effects**. All settings update live.
+
+| Setting | Default | Range |
+|---|---|---|
+| Enable | on | toggle |
+| Style | Ripple | Ripple / Pulse / Burst |
+| Color | `#FFFFFF` | color picker |
+| Size | 1.0 | 0.5–2.5 |
+| Duration (ms) | 600 | 200–1500 |
+| Line thickness | 2 | 1–8 |
+| Distinct right-click style | on | toggle |
+
+Size scales relative to the scene area, not the canvas, so effects look consistent across different export resolutions and padding settings.
+
+## Styles
+
+**Ripple** — two concentric rings that expand and fade out. The default; draws attention without dominating the frame.
+
+**Pulse** — a filled circle that scales up and fades. More visible than Ripple; good when you need clicks to read clearly in fast-paced content.
+
+**Burst** — eight radial lines extending from the click point. The most prominent; useful in short-form demos where every click needs to land immediately.
+
+When **Distinct right-click style** is on, right-clicks render with dashed lines so viewers can tell them apart from left-clicks at a glance.
+
+## Building from source
+
+```bash
+npm install
+npm run build      # one-off build
+npm run watch      # rebuild on save
+```
+
+Output goes to `dist/index.js`. The manifest `main` field points there.
+
+## How it works
+
+The extension registers a cursor effect via `registerCursorEffect`. Each click triggers a per-frame callback that draws the current animation frame onto Recordly's canvas and returns `true` until the duration elapses, then `false`. The same callback runs in both the editor preview and the export pipeline — what you see is what you get.
+
+## Permissions
+
+- `cursor` — to register click effects.
+- `ui` — to register the settings panel.
+
+No audio, timeline, file asset, or export access.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## Contributing
+
+Issues and pull requests welcome at [github.com/willytop8/recordly-click-ripple](https://github.com/willytop8/recordly-click-ripple). The extension API is documented in [EXTENSIONS.md](https://github.com/webadderallorg/Recordly/blob/main/EXTENSIONS.md).
+
+## Credits
+
+Built for [Recordly](https://www.recordly.dev) by [@webadderallorg](https://github.com/webadderallorg).

extension-examples/willytop8.click-ripple/build.mjs

@@ -0,0 +1,43 @@
+import { build, context } from "esbuild";
+import { copyFileSync, existsSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+const INSTALLED = join(
+  homedir(),
+  "Library/Application Support/Recordly/extensions/recordly-click-ripple/dist/index.js",
+);
+
+function deployToInstalled() {
+  if (existsSync(INSTALLED)) {
+    copyFileSync("dist/index.js", INSTALLED);
+    console.log("Deployed → " + INSTALLED);
+  }
+}
+
+const config = {
+  entryPoints: ["src/index.ts"],
+  outfile: "dist/index.js",
+  bundle: true,
+  format: "esm",
+  target: "es2022",
+  platform: "browser",
+  minify: false,
+  sourcemap: false,
+};
+
+if (process.argv.includes("--watch")) {
+  const ctx = await context({
+    ...config,
+    plugins: [{
+      name: "deploy-on-rebuild",
+      setup(b) { b.onEnd(() => deployToInstalled()); },
+    }],
+  });
+  await ctx.watch();
+  console.log("Watching src/ — Ctrl-C to stop");
+} else {
+  await build(config);
+  console.log("Built dist/index.js");
+  deployToInstalled();
+}

extension-examples/willytop8.click-ripple/dist/index.js

@@ -0,0 +1,127 @@
+// src/index.ts
+function activate(api) {
+  api.registerSettingsPanel({
+    id: "click-ripple-settings",
+    label: "Click Effects",
+    icon: "sparkles",
+    parentSection: "cursor",
+    fields: [
+      { id: "enabled", label: "Enable click effects", type: "toggle", defaultValue: true },
+      {
+        id: "style",
+        label: "Style",
+        type: "select",
+        defaultValue: "ripple",
+        options: [
+          { label: "Ripple (concentric rings)", value: "ripple" },
+          { label: "Pulse (filled fade)", value: "pulse" },
+          { label: "Burst (radial spokes)", value: "burst" }
+        ]
+      },
+      { id: "color", label: "Color", type: "color", defaultValue: "#FFFFFF" },
+      { id: "size", label: "Size", type: "slider", defaultValue: 1, min: 0.5, max: 2.5, step: 0.1 },
+      { id: "durationMs", label: "Duration (ms)", type: "slider", defaultValue: 600, min: 200, max: 1500, step: 50 },
+      { id: "thickness", label: "Line thickness", type: "slider", defaultValue: 2, min: 1, max: 8, step: 1 },
+      { id: "differentiateRightClick", label: "Distinct right-click style", type: "toggle", defaultValue: true }
+    ]
+  });
+  api.registerCursorEffect((ctx) => {
+    const enabled = api.getSetting("enabled") ?? true;
+    if (!enabled) return false;
+    const style = api.getSetting("style") ?? "ripple";
+    const color = api.getSetting("color") ?? "#FFFFFF";
+    const size = api.getSetting("size") ?? 1;
+    const durationMs = api.getSetting("durationMs") ?? 600;
+    const thickness = api.getSetting("thickness") ?? 2;
+    const differentiateRC = api.getSetting("differentiateRightClick") ?? true;
+    if (ctx.elapsedMs >= durationMs) return false;
+    const progress = ctx.elapsedMs / durationMs;
+    const isRightClick = ctx.interactionType === "right-click";
+    const distinct = isRightClick && differentiateRC;
+    const t = ctx.sceneTransform;
+    let x = ctx.cx * ctx.width;
+    let y = ctx.cy * ctx.height;
+    if (t != null && Number.isFinite(t.scale) && t.scale !== 0) {
+      x = (x - t.x) / t.scale;
+      y = (y - t.y) / t.scale;
+    }
+    const sceneWidth = ctx.videoLayout?.maskRect.width ?? ctx.width;
+    const baseRadius = sceneWidth * 0.04 * size;
+    switch (style) {
+      case "ripple":
+        drawRipple(ctx.ctx, x, y, progress, baseRadius, color, thickness, distinct);
+        break;
+      case "pulse":
+        drawPulse(ctx.ctx, x, y, progress, baseRadius, color, distinct);
+        break;
+      case "burst":
+        drawBurst(ctx.ctx, x, y, progress, baseRadius, color, thickness, distinct);
+        break;
+    }
+    return true;
+  });
+  api.log("Click Ripple activated");
+}
+function deactivate() {
+}
+function drawRipple(ctx, x, y, p, base, color, thick, distinct) {
+  const easeOut = (t) => 1 - Math.pow(1 - t, 3);
+  if (p > 0.15) {
+    const op = (p - 0.15) / 0.85;
+    drawRing(ctx, x, y, base * 1.4 * easeOut(op), color, thick, 1 - op, distinct);
+  }
+  drawRing(ctx, x, y, base * easeOut(p), color, thick, 1 - p, distinct);
+}
+function drawRing(ctx, x, y, r, color, thick, alpha, dashed) {
+  ctx.save();
+  ctx.globalAlpha = Math.max(0, Math.min(1, alpha));
+  ctx.strokeStyle = color;
+  ctx.lineWidth = thick;
+  if (dashed) ctx.setLineDash([thick * 2, thick * 2]);
+  ctx.beginPath();
+  ctx.arc(x, y, r, 0, Math.PI * 2);
+  ctx.stroke();
+  ctx.restore();
+}
+function drawPulse(ctx, x, y, p, base, color, distinct) {
+  const easeOut = (t) => 1 - Math.pow(1 - t, 2);
+  const r = base * 0.9 * easeOut(p);
+  const alpha = (1 - p) * 0.5;
+  ctx.save();
+  ctx.globalAlpha = alpha;
+  ctx.beginPath();
+  ctx.arc(x, y, r, 0, Math.PI * 2);
+  if (distinct) {
+    ctx.strokeStyle = color;
+    ctx.lineWidth = 3;
+    ctx.stroke();
+  } else {
+    ctx.fillStyle = color;
+    ctx.fill();
+  }
+  ctx.restore();
+}
+function drawBurst(ctx, x, y, p, base, color, thick, distinct) {
+  const easeOut = (t) => 1 - Math.pow(1 - t, 2);
+  const SPOKES = 8;
+  const innerR = base * 0.3 * easeOut(p);
+  const outerR = base * 1.1 * easeOut(p);
+  ctx.save();
+  ctx.globalAlpha = 1 - p;
+  ctx.strokeStyle = color;
+  ctx.lineWidth = thick;
+  ctx.lineCap = "round";
+  if (distinct) ctx.setLineDash([thick * 1.5, thick * 1.5]);
+  for (let i = 0; i < SPOKES; i++) {
+    const angle = i / SPOKES * Math.PI * 2;
+    ctx.beginPath();
+    ctx.moveTo(x + Math.cos(angle) * innerR, y + Math.sin(angle) * innerR);
+    ctx.lineTo(x + Math.cos(angle) * outerR, y + Math.sin(angle) * outerR);
+    ctx.stroke();
+  }
+  ctx.restore();
+}
+export {
+  activate,
+  deactivate
+};