Duplicate SVG clipPath IDs when sponsors share the same avatar

[lgc2333]

This issue was written by an LLM.

Describe the bug

SponsorKit used to crop circular avatars during image processing with sharp, so each rendered avatar did not need an SVG-level clipping definition.

After #95, circular cropping was moved into the generated SVG by emitting a <clipPath> for each avatar. That introduced per-avatar clipPath ids based on an incrementing counter. This avoided duplicate ids, but because badges are generated asynchronously, the counter assignment order could vary between runs, which caused the non-idempotent SVG output reported in #109.

#110 fixed #109 by making the clipPath id deterministic:

const cropId = `c${crypto.createHash("md5").update(base64Image).digest("hex").slice(0, 6)}`

However, this makes the id deterministic per image content, not per rendered avatar instance. When two or more sponsors use the same image data, for example the same fallback/default avatar, SponsorKit emits multiple elements with the same id.

In SVG, duplicate ids are invalid, and browsers resolve clip-path="url(#...)" against the first matching element. As a result, later avatars that share the same image can be clipped by the first avatar's rectangle instead of their own position, making those avatars appear blank or transparent in the generated SVG.

So this is a regression from the hash-based fix for #109: the SVG output is now stable, but shared-avatar cases can render incorrectly because clipPath ids are no longer unique per crop instance.

Proposed Fix

Use the deterministic render-order index directly for the SVG-local clipPath id.

The id only needs to be unique within the generated SVG document, so it does not need to be derived from the avatar image bytes. As long as the index comes from the already-determined sponsor/layout order, repeated generation with unchanged sponsor data will still produce the same SVG.

Reproduction

// sponsorkit.config.mjs

import { createHash } from 'node:crypto'

import { defineConfig, tierPresets } from 'sponsorkit'

const gravatarHash = createHash('md5').update('lgc2333@126.com').digest('hex')
const fallbackAvatar = `https://www.gravatar.com/avatar/${gravatarHash}?s=240&d=identicon`

const provider = {
  name: 'local',
  async fetchSponsors() {
    return [
      {
        sponsor: {
          type: 'User',
          login: 'alice',
          name: 'Alice',
          avatarUrl: '',
        },
        monthlyDollars: 20,
      },
      {
        sponsor: {
          type: 'User',
          login: 'bob',
          name: 'Bob',
          avatarUrl: '',
        },
        monthlyDollars: 10,
      },
    ]
  },
}

export default defineConfig({
  providers: [provider],
  outputDir: './sponsorkit',
  formats: ['svg'],
  fallbackAvatar,
  tiers: [{ preset: tierPresets.large }],
})

System Info

System:
  OS: Windows 11 10.0.26200
  CPU: (12) x64 Intel(R) Core(TM) i5-10400F CPU @ 2.90GHz
  Memory: 16.37 GB / 31.91 GB
Binaries:
  Node: 24.16.0 - D:\Program Files\nodejs\node.EXE
  npm: 11.13.0 - D:\Program Files\nodejs\npm.CMD
  pnpm: 11.15.1 - D:\Program Files\nodejs\pnpm.CMD
Browsers:
  Chrome: 150.0.7871.129
  Edge: Chromium (149.0.4022.52)

Observed with sponsorkit@17.1.1.

Used Package Manager

pnpm

Validations

• Follow our Code of Conduct
• Read the Contributing Guide.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• Check that this is a concrete bug. For Q&A, please open a GitHub Discussion instead.
• The provided reproduction is a minimal reproducible of the bug.

Contributions

• I am willing to submit a PR to fix this issue
• I am willing to submit a PR with failing tests (actually just go ahead and do it, thanks!)

[lgc2333]

本人英语水平较差，抱歉先使用了AI来撰写此issue。

起因是在我的工作流中会出现有人头像为空的情况，之后进行了一番调查：

发现 #110 后相同头像的clip path id会变成相同的，而在svg中，之后相同id的path会被忽略，从而导致头像不显示。

而 #109 ， #110 解决的问题是，之前重构头像到svg侧圆形修剪后，那边的实现定义的是一个全局counter，在每次生成中，由于头像收集是异步的，导致每次相同的数据，生成出来的svg数据不会固定。

所以针对这个问题的解决办法，不能回滚 #110 的目的。在 #122 的修复中，我引入了按渲染顺序指定crop id的实现。但是这个实现为部分函数加入了一个必选参数，break了接口兼容，如果觉得不妥，请继续与我探讨。

感谢审阅！

[lgc2333]

另外说一个不在此issue范围内的问题：

针对html内嵌多张svg标签，而不是使用img标签引用的情况，它们的clip path id会漏到全局，是后面其他svg的clip path定义不生效，从而导致后面的头像渲染不正常。

解决方法是在clip path前后加一些东西使它unique。在sponsorkit侧的实现方式最好是加一个cropid前后缀的配置项，不过我不确定是不是应该sponsorkit侧去解决这个问题，所以就先只提一下而不发pr/另外issue了