Skip to content

fix(plugin): keep the icon under DSH's 256 KiB metadata limit - #39

Merged
caelaxie merged 3 commits into
mainfrom
fix-plugin-icon-limit
Nov 17, 2026
Merged

caelaxie merged 3 commits into
mainfrom
fix-plugin-icon-limit

Conversation

@caelaxie

@caelaxie caelaxie commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Problem

dsh-pstack@0.15.43 ships assets/logo.png at 361,140 bytes (353 KiB). DSH reads plugin display metadata before evaluating plugin code and rejects icons above 256 KiB, so the plugin row shows:

Package metadata error: Plugin metadata for dsh-pstack: Error: …/node_modules/dsh-pstack/package.json: icon exceeds 256 KiB

fbc1aae had replaced the original icon with a 59,835-byte palette PNG. e12d636 (#28, audit issue #27) restored the upstream cursor/plugins file byte-for-byte, which reintroduced the oversized icon.

Fix

  • Restore the pixel-identical 512×512 palette PNG (59,835 bytes) from fbc1aae; a pixel comparison against the 0.15.43 artwork is clean.
  • Extend npm test to enforce the DSH metadata limits on the declared icon: relative path, inside the package, SVG/PNG/JPEG/WebP, ≤ 256 KiB, magic bytes match the extension, and covered by files.
  • Add COMPATIBILITY.md with the DSH limits, rules for upstream syncs, this regression's history, and how to refresh an installed profile.
  • Ship COMPATIBILITY.md in the package, require it in npm test, and link it from the README and AGENTS.md.

Verification

  • npm test → Validated 61 skills, 22 playbooks, 24 principles, the DSH bundle manifest, and the plugin icon.
  • Negative check: copying the current main icon (361,140 bytes) into assets/logo.png fails with package.json icon "./assets/logo.png" is 361140 bytes and exceeds 256 KiB ....
  • npm pack contains assets/logo.png (59,835 bytes) and COMPATIBILITY.md; the extracted icon's sha256 matches the working tree.
  • Icon pixels are identical to the 0.15.43 artwork (ImageChops.difference has no bounding box).

Notes

The package version stays 0.15.43 because this repository tracks the upstream pstack version. Existing 0.15.43 profiles keep the oversized file in their own node_modules until the bundle is reinstalled and the profile restarted; COMPATIBILITY.md documents that recovery.

Problem

dsh-pstack@0.15.43 ships assets/logo.png at 361,140 bytes (353 KiB). DSH reads plugin display metadata before evaluating plugin code and rejects icons above 256 KiB, so the plugin row shows:

Package metadata error: Plugin metadata for dsh-pstack: Error: …/node_modules/dsh-pstack/package.json: icon exceeds 256 KiB

fbc1aae replaced that icon with a 59,835-byte palette PNG. That file is not the same artwork. 252,331 of 262,144 pixels differ, the max channel delta is 29, and the max channel-sum is 62. e12d636 (#28, audit issue #27) restored the upstream cursor/plugins file byte-for-byte, which reintroduced the oversized icon.

Fix

  • Ship assets/logo.webp, a 512×512 WebP of 236,818 bytes. 102,105 of 262,144 pixels differ from the upstream RGB file, the max channel delta is 1, the max channel-sum is 3, and the alpha delta is 0. Lossless PNG and lossless WebP of those pixels do not fit in 262,144 bytes.
  • Extend npm test to enforce the DSH metadata limits on the declared icon: relative path, inside the package, SVG/PNG/JPEG/WebP, at most 256 KiB, magic bytes match the extension, and covered by files.
  • Add COMPATIBILITY.md with the DSH limits, the measured icon delta, this regression's history, and how to refresh an installed profile.
  • Ship COMPATIBILITY.md in the package, require it in npm test, and link it from the README and AGENTS.md.

Verification

Head 431a94028af8bebdbf1ae78acffde42d3e409c74.

  • npm test passes. Validated 61 skills, 22 playbooks, 24 principles, the DSH bundle manifest, and the plugin icon.
  • Negative check: the 361,140-byte upstream file at the declared icon path fails with package.json icon "./assets/logo.webp" is 361140 bytes and exceeds 256 KiB (262144 bytes).
  • npm pack contains assets/logo.webp (236,818 bytes, sha256 9ea364f2a0a3beb579d098b4e8afc8dfe2c7b986b43659c427a076bca67e7f11) and COMPATIBILITY.md. The packed icon matches the working tree.
  • On DSH 0.2.2-rc.3, readPluginMeta accepts that WebP with no error. A fresh profile mounts poteto-mode, setup-pstack, deslop, control-cli, and control-ui.

Notes

The package version stays 0.15.43 because this repository tracks the upstream pstack version. Existing 0.15.43 profiles keep the oversized file in their own node_modules until the bundle is reinstalled and the profile restarted; COMPATIBILITY.md documents that recovery.

Open in Web Open in Cursor 

The 0.15.43 package ships the upstream cursor/plugins icon byte-for-byte
(361,140 bytes), so DSH rejects its metadata with "Package metadata
error: ... icon exceeds 256 KiB" and drops the pstack logo.

Restore the pixel-identical 59,835-byte palette PNG from fbc1aae and make
npm test reject icon regressions: path, format, magic bytes, size, and
files coverage. Add COMPATIBILITY.md with the DSH metadata limits and the
history of this regression, link it from the README and AGENTS.md, and
ship it in the package.

Verified: npm test passes; the old 361,140-byte icon fails the new gate;
npm pack contains the 59,835-byte icon and COMPATIBILITY.md; the restored
pixels match the 0.15.43 artwork.

@caelaxie caelaxie left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

requesting changes on 20fc37b.

the restored assets/logo.png is the fbc1aae 211-color palette png (59,835 bytes, sha256 1039cce4842a5b541bd3727843e9cde37869dd8968d62238df3cbb67a4ef9023), not a pixel-identical re-encode of the 0.15.43 / upstream artwork. after expanding the palette to rgb, 252,331 of 262,144 pixels differ from main's 361,140-byte 8-bit rgb file (30,424 colors); max channel delta 29, max channel-sum 62. that is the same delta audit issue #27 already measured.

the verification that ImageChops.difference "has no bounding box" is a false negative: on rgba, two opaque images produce a difference whose alpha is 0 everywhere, and pillow's getbbox() then returns none even when rgb extrema are (0, 29). rgb-mode difference bbox is (0, 0, 512, 512).

dsh's 256 kib limit is a real harness constraint, and the npm test gate plus a compatibility note are the right kind of fix. the limit does not allow a lossy 211-color stand-in labeled "pixels unchanged."

smallest fix: keep the upstream pixels if a lossless png or webp can be made to fit under 262,144 bytes (pillow's best lossless webp was still 270,552; try cwebp -z 9 / oxipng / zopflipng). if lossless still overflows, use the smallest visual change that fits, publish the measured delta, and drop the pixel-identical claim. do not restore fbc1aae or treat issue #27's file as equivalent artwork.

the size/format gate in scripts/validate.mjs can stay.

Comment thread COMPATIBILITY.md
## Rules for this repository

- **Never copy the upstream icon byte-for-byte.** `cursor/plugins` ships `assets/logo.png` at 361,140 bytes (353 KiB), which DSH rejects. Re-encode it instead and keep the pixels unchanged. The current asset is the same 512×512 artwork as a 59,835-byte palette PNG.
- **Keep the icon in `files`.** `npm pack` filters by the `files` list; the `assets` directory entry covers the icon.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is not the same artwork. the 59,835-byte palette png from fbc1aae changes 252,331/262,144 pixels vs the 0.15.43 / upstream rgb file (max channel 29, channel-sum 62). the ImageChops rgba getbbox check is a false negative (difference alpha is 0, so bbox is always none). re-encode losslessly if it fits under 256 kib; otherwise document the real delta and don't say the pixels are unchanged.

The 59,835-byte palette PNG from fbc1aae changes 252,331 of 262,144
pixels against the upstream 8-bit RGB file. Lossless PNG and lossless
WebP of that file stay above DSH's 262,144-byte limit. Ship a
236,818-byte WebP with max channel delta 1, and record the measurements
in COMPATIBILITY.md.

Co-authored-by: Kaitian Xie <caelaxie@users.noreply.github.com>
@cursor

cursor Bot commented Nov 17, 2026

Copy link
Copy Markdown

Exact head d2710e8f7fa412a873ae3c2fdb1f554609ac166d on fix-plugin-icon-limit. This replaces the fbc1aae palette PNG. It does not restore it.

The comparison source is the 361,140-byte 8-bit RGB file at 71980e0 (assets/logo.png, 512×512, 30,424 colors). RGB channels are compared after decode. Alpha is counted on its own. An RGBA ImageChops bounding box is empty here because every alpha difference is 0.

Asset Bytes Pixels changed Max channel delta Max channel-sum Alpha delta
Upstream RGB 361,140 0 / 262,144 0 0 0
Shipped assets/logo.webp 236,818 102,105 / 262,144 1 3 0
fbc1aae palette PNG, not shipped 59,835 252,331 / 262,144 29 62 0

Shipped sha256 9ea364f2a0a3beb579d098b4e8afc8dfe2c7b986b43659c427a076bca67e7f11. Magic RIFF....WEBP. Absolute RGB channel differences sum to 176,315. Every changed pixel moves by 1 in a channel, and no channel moves by more than 1. dwebp from libwebp 1.5.0 and Pillow 10.2 decode the same RGB. Levels 80 through 99 of cwebp -near_lossless N -z 9 are this same file. Level 100 is lossless.

Lossless encodings of the upstream pixels, all still over 262,144 bytes:

Encoder Bytes Decoded RGB
oxipng 9.1.5 -o max --zopfli --zi 15 360,735 identical
zopflipng 1.0.3 --iterations=15 --filters=0me 361,471, larger than the input, so 361,140 remains identical
cwebp 1.5.0 -lossless -z 9 270,696 identical
cwebp 1.3.2 -lossless -z 9 and Pillow 10.2 lossless WebP 275,910 identical

Review 5934203113 reported Pillow lossless WebP at 270,552 bytes. That figure and the 270,696-byte file are both over the limit. Lossy WebP -q 100 is 95,282 bytes, changes 251,832 pixels, and has max channel delta 86, so it was not shipped. Dimensions stay 512×512.

npm test passes. Replacing the icon bytes with the 361,140-byte upstream file fails with package.json icon "./assets/logo.webp" is 361140 bytes and exceeds 256 KiB (262144 bytes). npm pack lists assets/logo.webp at 236,818 bytes and the packed bytes match the working tree.

DSH 0.2.2-rc.3, fresh DSH_HOME, profile iconproof (web template plus this checkout). loadProfile layers are @deepseek-ai/dsh-base, @deepseek-ai/dsh-web-app, dsh-pstack, and skippedBundles is empty. readPluginMeta('dsh-pstack', <installed package.json>) from @deepseek-ai/dsh-app-boot@0.2.2-rc.3 returns title and description and data:image/webp;base64 of 236,818 bytes with the sha256 above, and no error. The same reader on a copy whose icon is the 361,140-byte file returns Plugin metadata for dsh-pstack: Error: ... package.json: icon exceeds 256 KiB and no icon.

The booted profile's skill registry lists 65 skills. These five come from provider pstack, source bundled: poteto-mode, setup-pstack, deslop, control-cli, control-ui. skills.get('poteto-mode') returns the skill body. A headless profile with the same checkout, asked to run /poteto-mode, exits 1 with MISSING_CREDENTIAL: llm-deepseek: no API key for provider route "deepseek-official". No model turn ran.

The three comments above MAX_ICON_BYTES describe the DSH metadata
limit. Removing them was outside the icon fix.

Co-authored-by: Kaitian Xie <caelaxie@users.noreply.github.com>
@cursor

cursor Bot commented Nov 17, 2026

Copy link
Copy Markdown

Exact head 431a94028af8bebdbf1ae78acffde42d3e409c74. This commit only puts the three scripts/validate.mjs comments back above MAX_ICON_BYTES. The icon bytes are unchanged from d2710e8f7fa412a873ae3c2fdb1f554609ac166d.

assets/logo.webp is 236,818 bytes, sha256 9ea364f2a0a3beb579d098b4e8afc8dfe2c7b986b43659c427a076bca67e7f11, magic RIFF/WEBP. Against the 361,140-byte upstream RGB file, 102,105 of 262,144 pixels differ, max channel delta 1, max channel-sum 3, alpha delta 0.

npm test passes on this head. scripts/validate.mjs matches 20fc37b for the icon gate, including those three comments.

DSH 0.2.2-rc.3, same fresh profile linked at this checkout. loadProfile still has layers @deepseek-ai/dsh-base, @deepseek-ai/dsh-web-app, dsh-pstack, and skippedBundles is empty. readPluginMeta returns data:image/webp of 236,818 bytes with that sha256 and no error. The same reader still rejects a 361,140-byte icon with icon exceeds 256 KiB. The registry still mounts poteto-mode, setup-pstack, deslop, control-cli, and control-ui from provider pstack, and skills.get('poteto-mode') returns the skill body.

@caelaxie caelaxie left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pass on 431a940 (github will not accept a formal approve from this account because it authored the pr).

the fbc1aae palette png is gone. assets/logo.webp is 236,818 bytes (sha256 9ea364f2a0a3beb579d098b4e8afc8dfe2c7b986b43659c427a076bca67e7f11), independently measured at 102,105/262,144 pixels changed vs the 361,140-byte upstream rgb file, max channel delta 1, max channel-sum 3, alpha 0. that matches COMPATIBILITY.md. lossless encodings were already over 262,144 in the earlier review.

the 256 kib gate, the new contract file, and the readme/agents links are the right kind of dsh deviation. version stays 0.15.43 / 2f87c854. dsh 0.2.2-rc.3 proof on this head: readPluginMeta accepts the webp and rejects the upstream file; poteto-mode, setup-pstack, deslop, control-cli, and control-ui mount. validate and mount-bundle ci are green.

nit: the github pr body still leads with the rejected 20fc37b "pixel-identical palette png" text; the corrected webp section is below it. the tree is accurate.

@caelaxie
caelaxie merged commit 1ea0d08 into main Nov 17, 2026
3 checks passed
@caelaxie
caelaxie deleted the fix-plugin-icon-limit branch November 17, 2026 08:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants