The release DMG builds and contains ICCery.app + an Applications symlink, but Finder shows the default grey icon-view window instead of the ice-cream / wordmark background. The PNG assets are in git and dmgbuild-settings.py points at them. This is cosmetic only — install still works.
Observed on the v2.0.0-pre2-grok package job (Actions run 29714) which produced ICCery-2.0.0-1.dmg with dmgbuild 1.6.5.
Spec / history
docs/23-assets.md — installer chrome is dmg-background.png + @2x + .svg (v1 path was icons/; v2 files live under Resources/).
docs/24-issues-invariants.md #189 — “DMG has no background image”. AppleScript Finder decoration does not run headlessly. Invariant: use dmgbuild, not Finder AppleScript.
Follow-ups cited there: #196, #208, #219, then dmgbuild (#222, commit 6976ced on v1).
docs/26-v2-mac-ticket-plan.md M6 packaging: “dmgbuild with background art (not Finder AppleScript, #189)”.
scripts/package-release.sh never exports DMG_BACKGROUND. CWD at dmgbuild time is the repo root, so Resources/dmg-background.pngdoes exist and background is not cleared to None. Run 29714 logged no missing-file fallback; it only printed DMG: …/ICCery-2.0.0-1.dmg.
Parallel TIFF path that does not feed the DMG
The Release xcodebuild on the same job already ran:
Log line: “2 images written to …/dmg-background.tiff”.
That HiDPI TIFF is the format Finder historically accepts as a window picture. It is copied into the .app bundle, not into the DMG volume. dmgbuild is still pointed at the 1x RGBA PNG. The @2x PNG is unused for the installer window.
Xcode does this because project.yml includes the whole Resources/ tree in the app target (excludes only entitlements + Argyll). So the TIFF is an app-resource side effect, not a DMG input.
Likely causes (independent; any one is enough)
dmgbuild 1.6.5 vs current Finder. CI installed dmgbuild-1.6.5 ds_store-1.3.1 mac_alias-2.2.2. 1.6.5 writes the window background as a legacy Alias (backgroundImageAlias) in .DS_Store. On recent Finder (Sequoia / Tahoe) that alias often does not resolve after the RW image is converted to compressed read-only UDZO, so the window falls back to the default grey background. Same class of bug fixed in dmgbuild 1.6.7 (bookmark-based background; Plover #1804 / PR #1821 on macOS 26.2 Tahoe).
PNG + alpha as Finder wallpaper. The 1x asset is color type 6 (RGBA). Finder has a long history of ignoring PNG-with-alpha window pictures. Projects that actually show a background pass a flattened TIFF (often the tiffutil -cathidpicheck pair).
Bitmap size == window size.window_rect width/height is 660×400 and the 1x PNG is exactly 660×400. Finder icon-view chrome (title bar, padding) clips or shifts an exact-fit picture; it can look like “no background” even when .DS_Store points at the file. Usual practice is a slightly larger bitmap than the window.
Stale comments / docs, not a runtime skip. The settings file still says background art “can be supplied later”. docs/23 still lists icons/dmg-background.png. Neither prevents the file being passed through.
What it is not
Missing asset (both PNGs are in git).
background = None from a bad relative path (path is valid from repo root).
The TIFF step failing (it succeeds, just in the wrong place).
A Gatekeeper / notarization failure — this is window chrome only.
Acceptance
Mount ICCery-*.dmg produced by scripts/package-release.sh on a clean Mac (and on the self-hosted runner OS).
Finder icon-view window shows the cone + wordmark scene, not the default grey background.
ICCery.app stays left, Applications alias stays right; no visible .background file in the window.
Retina display uses the 2x layer (no blurry upscale of the 1x PNG).
Headless CI only — no Finder AppleScript (#189 invariant).
Proposed fix (do not implement in this ticket’s first pass unless attached to a packaging PR)
Pin dmgbuild ≥ 1.6.7 in scripts/package-release.sh (pip install 'dmgbuild>=1.6.7').
Before dmgbuild, build a HiDPI TIFF next to the settings file:
Export DMG_BACKGROUND to that TIFF (or hard-code it in dmgbuild-settings.py).
Optionally enlarge the bitmap (or shrink window_rect) so Finder chrome does not clip the art.
Stop shipping dmg-background.png / @2x / .tiff inside ICCery.app unless something in-app actually uses them — today they are only installer chrome. project.ymlResources/ exclude would do that.
Update docs/23 path (Resources/, not icons/) and delete the “supplied later” comment.
Test
Local: scripts/package-release.sh then mount the DMG; screenshot the window.
CI: package job on a v* tag; download the release asset; mount on the runner OS and a second Mac.
Negative: temporarily rename the TIFF and confirm we fail loud rather than silently shipping a grey window (background missing should be an error, not None).
Out of scope
Redesigning the background art.
Finder AppleScript decoration.
Notarization / Developer ID (separate from window chrome).
## Summary
The release DMG builds and contains `ICCery.app` + an Applications symlink, but Finder shows the **default grey icon-view window** instead of the ice-cream / wordmark background. The PNG assets are in git and `dmgbuild-settings.py` points at them. This is cosmetic only — install still works.
Observed on the `v2.0.0-pre2-grok` package job (Actions run 29714) which produced `ICCery-2.0.0-1.dmg` with dmgbuild **1.6.5**.
## Spec / history
- docs/23-assets.md — installer chrome is `dmg-background.png` + `@2x` + `.svg` (v1 path was `icons/`; v2 files live under `Resources/`).
- docs/24-issues-invariants.md **#189** — “DMG has no background image”. AppleScript Finder decoration does not run headlessly. Invariant: use `dmgbuild`, not Finder AppleScript.
- Follow-ups cited there: #196, #208, #219, then **dmgbuild** (#222, commit `6976ced` on v1).
- docs/26-v2-mac-ticket-plan.md M6 packaging: “dmgbuild with background art (**not** Finder AppleScript, #189)”.
- Related packaging ticket: #32.
This is a **regression of the #189 symptom** on v2, not a missing file.
## What is already set up (so this is not “asset not added”)
| Path | Format |
|---|---|
| `Resources/dmg-background.png` | 660×400, 8-bit **RGBA** PNG (~9 KB) |
| `Resources/dmg-background@2x.png` | 1320×800, 8-bit **RGBA** PNG (~22 KB) |
| `brand/dmg-background.svg` | source |
`scripts/dmgbuild-settings.py`:
```python
background = os.environ.get('DMG_BACKGROUND', 'Resources/dmg-background.png')
if background and not os.path.exists(background):
background = None
window_rect = ((100, 100), (660, 400))
default_view = 'icon-view'
icon_locations = {
'ICCery.app': (180, 220),
'Applications': (480, 220),
}
```
`scripts/package-release.sh` never exports `DMG_BACKGROUND`. CWD at `dmgbuild` time is the repo root, so `Resources/dmg-background.png` **does exist** and `background` is **not** cleared to `None`. Run 29714 logged no missing-file fallback; it only printed `DMG: …/ICCery-2.0.0-1.dmg`.
## Parallel TIFF path that does *not* feed the DMG
The Release xcodebuild on the same job already ran:
```
tiffutil -cathidpicheck \
Resources/dmg-background.png \
Resources/dmg-background@2x.png \
-out ICCery.app/Contents/Resources/dmg-background.tiff
```
Log line: “2 images written to …/dmg-background.tiff”.
That HiDPI TIFF is the format Finder historically accepts as a **window picture**. It is copied **into the .app bundle**, not into the DMG volume. dmgbuild is still pointed at the **1x RGBA PNG**. The `@2x` PNG is unused for the installer window.
Xcode does this because `project.yml` includes the whole `Resources/` tree in the app target (`excludes` only entitlements + Argyll). So the TIFF is an app-resource side effect, not a DMG input.
## Likely causes (independent; any one is enough)
1. **dmgbuild 1.6.5 vs current Finder.** CI installed `dmgbuild-1.6.5 ds_store-1.3.1 mac_alias-2.2.2`. 1.6.5 writes the window background as a legacy Alias (`backgroundImageAlias`) in `.DS_Store`. On recent Finder (Sequoia / Tahoe) that alias often does not resolve after the RW image is converted to compressed read-only UDZO, so the window falls back to the default grey background. Same class of bug fixed in **dmgbuild 1.6.7** (bookmark-based background; Plover #1804 / PR #1821 on macOS 26.2 Tahoe).
2. **PNG + alpha as Finder wallpaper.** The 1x asset is color type 6 (RGBA). Finder has a long history of ignoring PNG-with-alpha window pictures. Projects that actually show a background pass a flattened **TIFF** (often the `tiffutil -cathidpicheck` pair).
3. **Bitmap size == window size.** `window_rect` width/height is 660×400 and the 1x PNG is exactly 660×400. Finder icon-view chrome (title bar, padding) clips or shifts an exact-fit picture; it can look like “no background” even when `.DS_Store` points at the file. Usual practice is a slightly larger bitmap than the window.
4. **Stale comments / docs, not a runtime skip.** The settings file still says background art “can be supplied later”. docs/23 still lists `icons/dmg-background.png`. Neither prevents the file being passed through.
## What it is not
- Missing asset (both PNGs are in git).
- `background = None` from a bad relative path (path is valid from repo root).
- The TIFF step failing (it succeeds, just in the wrong place).
- A Gatekeeper / notarization failure — this is window chrome only.
## Acceptance
- Mount `ICCery-*.dmg` produced by `scripts/package-release.sh` on a clean Mac (and on the self-hosted runner OS).
- Finder icon-view window shows the cone + wordmark scene, not the default grey background.
- `ICCery.app` stays left, Applications alias stays right; no visible `.background` file in the window.
- Retina display uses the 2x layer (no blurry upscale of the 1x PNG).
- Headless CI only — no Finder AppleScript (#189 invariant).
## Proposed fix (do not implement in this ticket’s first pass unless attached to a packaging PR)
1. Pin **dmgbuild ≥ 1.6.7** in `scripts/package-release.sh` (`pip install 'dmgbuild>=1.6.7'`).
2. Before `dmgbuild`, build a HiDPI TIFF next to the settings file:
```
tiffutil -cathidpicheck \
Resources/dmg-background.png \
Resources/dmg-background@2x.png \
-out build/dmg-background.tiff
```
Export `DMG_BACKGROUND` to that TIFF (or hard-code it in `dmgbuild-settings.py`).
3. Optionally enlarge the bitmap (or shrink `window_rect`) so Finder chrome does not clip the art.
4. Stop shipping `dmg-background.png` / `@2x` / `.tiff` inside `ICCery.app` unless something in-app actually uses them — today they are only installer chrome. `project.yml` `Resources/` exclude would do that.
5. Update docs/23 path (`Resources/`, not `icons/`) and delete the “supplied later” comment.
## Test
- Local: `scripts/package-release.sh` then mount the DMG; screenshot the window.
- CI: package job on a `v*` tag; download the release asset; mount on the runner OS and a second Mac.
- Negative: temporarily rename the TIFF and confirm we fail loud rather than silently shipping a grey window (`background` missing should be an error, not `None`).
## Out of scope
- Redesigning the background art.
- Finder AppleScript decoration.
- Notarization / Developer ID (separate from window chrome).
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Summary
The release DMG builds and contains
ICCery.app+ an Applications symlink, but Finder shows the default grey icon-view window instead of the ice-cream / wordmark background. The PNG assets are in git anddmgbuild-settings.pypoints at them. This is cosmetic only — install still works.Observed on the
v2.0.0-pre2-grokpackage job (Actions run 29714) which producedICCery-2.0.0-1.dmgwith dmgbuild 1.6.5.Spec / history
dmg-background.png+@2x+.svg(v1 path wasicons/; v2 files live underResources/).dmgbuild, not Finder AppleScript.6976cedon v1).This is a regression of the #189 symptom on v2, not a missing file.
What is already set up (so this is not “asset not added”)
Resources/dmg-background.pngResources/dmg-background@2x.pngbrand/dmg-background.svgscripts/dmgbuild-settings.py:scripts/package-release.shnever exportsDMG_BACKGROUND. CWD atdmgbuildtime is the repo root, soResources/dmg-background.pngdoes exist andbackgroundis not cleared toNone. Run 29714 logged no missing-file fallback; it only printedDMG: …/ICCery-2.0.0-1.dmg.Parallel TIFF path that does not feed the DMG
The Release xcodebuild on the same job already ran:
Log line: “2 images written to …/dmg-background.tiff”.
That HiDPI TIFF is the format Finder historically accepts as a window picture. It is copied into the .app bundle, not into the DMG volume. dmgbuild is still pointed at the 1x RGBA PNG. The
@2xPNG is unused for the installer window.Xcode does this because
project.ymlincludes the wholeResources/tree in the app target (excludesonly entitlements + Argyll). So the TIFF is an app-resource side effect, not a DMG input.Likely causes (independent; any one is enough)
dmgbuild-1.6.5 ds_store-1.3.1 mac_alias-2.2.2. 1.6.5 writes the window background as a legacy Alias (backgroundImageAlias) in.DS_Store. On recent Finder (Sequoia / Tahoe) that alias often does not resolve after the RW image is converted to compressed read-only UDZO, so the window falls back to the default grey background. Same class of bug fixed in dmgbuild 1.6.7 (bookmark-based background; Plover #1804 / PR #1821 on macOS 26.2 Tahoe).tiffutil -cathidpicheckpair).window_rectwidth/height is 660×400 and the 1x PNG is exactly 660×400. Finder icon-view chrome (title bar, padding) clips or shifts an exact-fit picture; it can look like “no background” even when.DS_Storepoints at the file. Usual practice is a slightly larger bitmap than the window.icons/dmg-background.png. Neither prevents the file being passed through.What it is not
background = Nonefrom a bad relative path (path is valid from repo root).Acceptance
ICCery-*.dmgproduced byscripts/package-release.shon a clean Mac (and on the self-hosted runner OS).ICCery.appstays left, Applications alias stays right; no visible.backgroundfile in the window.Proposed fix (do not implement in this ticket’s first pass unless attached to a packaging PR)
Pin dmgbuild ≥ 1.6.7 in
scripts/package-release.sh(pip install 'dmgbuild>=1.6.7').Before
dmgbuild, build a HiDPI TIFF next to the settings file:Export
DMG_BACKGROUNDto that TIFF (or hard-code it indmgbuild-settings.py).Optionally enlarge the bitmap (or shrink
window_rect) so Finder chrome does not clip the art.Stop shipping
dmg-background.png/@2x/.tiffinsideICCery.appunless something in-app actually uses them — today they are only installer chrome.project.ymlResources/exclude would do that.Update docs/23 path (
Resources/, noticons/) and delete the “supplied later” comment.Test
scripts/package-release.shthen mount the DMG; screenshot the window.v*tag; download the release asset; mount on the runner OS and a second Mac.backgroundmissing should be an error, notNone).Out of scope