Skip to content

fix(release): restore the macOS icon at 16px and 32px - #5529

Open
sunrioa wants to merge 1 commit into
apache:mainfrom
sunrioa:fix/macos-icon-small-sizes
Open

sunrioa wants to merge 1 commit into
apache:mainfrom
sunrioa:fix/macos-icon-small-sizes

Conversation

@sunrioa

@sunrioa sunrioa commented Sep 20, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Bump electron-builder from 26.15.3 to 26.16.1.
  • Move the reproducible-ZIP app-builder-lib patch to the new version and update its LICENSE entry.
  • Assert in the macOS packaging verifier that the bundled icon carries 16px and 32px art macOS can draw.

electron-builder 26.15.2 replaced its icon generator, and from then through 26.15.3 the icon it produced stored the 16px and 32px faces as PNG in the legacy icp4/icp5/icp6 slots. macOS does not decode those slots, so Finder list rows, the Trash, Activity Monitor and the mounted installer volume rendered noise while 128px and up stayed correct and hid the breakage. 26.16.0 fixed it upstream by writing those sizes as ic04/ic05 ARGB again.

The icon is produced by a toolset electron-builder downloads at build time, so the version pin does not describe the artifact it yields. verifyPackagedMacApp now reads the bundled icon.icns and rejects PNG in the legacy slots, which is the check that would have caught this before it shipped.

The patch is still needed. 26.16.1 sets -mtm=off and -mta=off for 7z archives upstream, but still not in the zip branch that Windows artifacts take, so only the patch filename and its LICENSE entry change.

Fixes #5528

Verification

  • npm run lint
  • npm run format:check
  • npm run typecheck
  • npx knip --workspace apps/desktop
  • npx knip --workspace packages/ui
  • npm run check:asf-source — 92/92 passed
  • npm run check:release — 206/207 passed
  • node --test scripts/verify-packaged-app.test.mjs — 25/25 passed
  • node --test scripts/verify-packaged-app-icons.test.mjs scripts/generate-app-icons.test.mjs — 7/7 passed
  • Ran both icons toolsets by hand on apps/desktop/assets/app-icons/sky.png. Toolset 1.1.0, which 26.15.3 pins, reproduced the shipped icon byte for byte at 159,115 bytes with PNG in the legacy slots. Toolset 1.2.3, which 26.16.1 pins, produced 123,793 bytes with ARGB small sizes that render at 16px.
  • Ran the new guard against real artifacts. It rejects the shipped 0.2.0-dev.43 icon, reporting PNG data in the slots macOS does not render, and accepts the same source PNG regenerated with the toolset 26.16.1 pins.
  • patch-package --error-on-fail applies the regenerated patch to a pristine app-builder-lib@26.16.1, and the zip branch carries both flags again afterwards.

The single check:release failure is qualify-released-cli-state-root.test.mjs timing out while a full build ran alongside it. It passes 12/12 in isolation and the file never mentions electron-builder or icons.

verify:macos end to end is unrun because it needs the release signing credentials. The icon assertion it gained is covered by the unit tests above and by the artifact run quoted here.

CI is green except test, which failed on two different WorkHub cases across two runs of the same tree: e2e/workhub-layout.spec.ts:26, which also fails on clean main at 87ff279 with the same assertion and line, and the WorkHub native browser presentation smoke under xvfb. None of the packages the lockfile moved are imported anywhere under apps/desktop/src or packages/*/src, and the Electron version is unchanged, so neither case can reach this diff.

To see the defect directly:

iconutil --convert iconset -o /tmp/maka.iconset /Applications/Maka.app/Contents/Resources/icon.icns
open /tmp/maka.iconset/icon_16x16.png

Review focus

The lockfile carries the electron-builder family and its transitive drift. The one direction worth a look is @noble/hashes 2.2.0 to 1.8.0, which is not a downgrade this change chose: app-builder-lib 26.16.1 declares ^1.8.0 where 26.15.3 declared ^2.2.0, and nothing outside app-builder-lib and pkijs depends on it. Every new resolved URL stays on registry.npmjs.org, and the lockfile was regenerated with the pinned npm 11.19.0.

AI use

Select exactly one:

  • No generative tool made a substantive contribution
  • Generative tooling made a substantive contribution

Tool(s) and scope:

Claude Code assisted with the ICNS slot diagnosis, locating the upstream regression and its fix, the verifier guard and its regression tests, and drafting this description. I reproduced both toolsets against the shipped artifacts and reviewed the final diff, the lockfile, and the test results before submission.

Checklist

  • Tests cover the change and fail without it
  • Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

  • Yes — described under Summary above
  • No

@github-actions github-actions Bot added the effort/M Under 500 readable lines label Sep 20, 2026
@sunrioa
sunrioa marked this pull request as draft September 20, 2026 07:32
@sunrioa
sunrioa force-pushed the fix/macos-icon-small-sizes branch 2 times, most recently from b22fe34 to 30164a5 Compare September 20, 2026 07:38
electron-builder 26.15.2 replaced its icon generator, and from then until
26.15.3 the .icns it produced stored the 16px and 32px faces as PNG data in
the legacy icp4/icp5/icp6 slots. macOS does not decode those, so every place
that draws the icon small — Finder list rows, the Trash, Activity Monitor,
and the installer DMG's own volume icon — showed noise, while 128px and up
stayed correct and hid the breakage.

26.16.1 carries the upstream fix (icons toolset 1.2.3), which writes those
sizes as ic04/ic05 ARGB again.

The icon comes from a toolset the builder downloads at build time, so a
version pin alone says nothing about what was produced. The macOS packaging
verifier now reads the bundled icon and rejects the broken shape, which is
the check that would have caught this before it shipped.

The reproducible-ZIP patch moves to the new version unchanged. 26.16.1 sets
-mtm=off and -mta=off for 7z archives upstream but still not for zip, which
is the branch Windows artifacts take.

Refs: electron-userland/electron-builder#9940

Generated-by: Claude Code
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@sunrioa
sunrioa force-pushed the fix/macos-icon-small-sizes branch from 30164a5 to 000ceb3 Compare September 20, 2026 07:56
@sunrioa
sunrioa marked this pull request as ready for review September 20, 2026 09:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

effort/M Under 500 readable lines

Projects

None yet

Development

Successfully merging this pull request may close these issues.

macOS app and installer icon renders as noise at 16px and 32px

1 participant