Skip to content

macOS DMG: branded window background and icon layout - #272

Merged
echelon merged 2 commits into
storytold:mainfrom
XusBadia:dmg-background
Oct 9, 2026
Merged

echelon merged 2 commits into
storytold:mainfrom
XusBadia:dmg-background

Conversation

@XusBadia

@XusBadia XusBadia commented Oct 8, 2026 •

Copy link
Copy Markdown

What

The macOS DMG opened as a plain white Finder window. It now opens like this:

PdfCraft DMG window in Finder

The icon's figure as a cover on the PdfCraft colour field, PdfCraft.app and the Applications link side by side on Paper, and a small PdfCraft-specific touch: the arrow and the mono line under the title come from the app's craft. Ink, Paper and the app colour only; Inter and JetBrains Mono.

How

Same approach as PhotoCraft's and VectorCraft's, which have landed (storytold/photocraft#1201, storytold/vectorcraft#493):

  • packaging/macos/dmg/background.svg: the source. Its text is outlined, so rendering it needs no fonts, and the figure is an <image> of the existing icon in assets/app-icon/.
  • background.tiff: 1x 660×400 + 2x 1320×800 in one HiDPI TIFF (16-colour palette, Deflate, sRGB; ~95 KB, no paper grain), as PhotoCraft's.
  • dmg-layout.DS_Store: Finder's view settings (window 660×400 content, icon size 128, PdfCraft.app at (326, 205), Applications at (574, 205), the background). It's named so it isn't mistaken for, or ignored like, a Finder-generated .DS_Store.
  • generate.py: writes both from the SVG on any OS (pip install 'pillow>=12' ds_store==1.3.3 mac_alias==2.2.3, resvg on PATH). The output is byte-for-byte reproducible and carries nothing from the machine that ran it: no paths, users, disk names or volume UUIDs.
  • package.sh copies the TIFF and the layout into the staging folder. The image is still built with hdiutil makehybrid, and nothing extra runs in the signing job.

One behaviour change: the volume name drops the version

.DS_Store points at the background through an alias that includes the volume name. With PdfCraft <version> Finder kept the window and icon positions but lost the background (tested). So the mounted volume is now called PdfCraft; the DMG file name still carries the version.

Tested

  • Built the image with the exact package.sh steps (staging folder, makehybrid, UDZO) around a stub PdfCraft.app with the real icon, mounted it and opened it in Finder on macOS: the screenshot above is that DMG.
  • Finder draws icon labels in black in both light and dark appearance when the window has a background (checked in both), so the label area stays light.
  • Margin check: no artwork within 10 pt of either 128 pt icon box or of the label strips (pixel diff of the background against the same background without artwork).
  • shellcheck clean; cargo xtask assets passes where the repo has it; generate.py reproduces the committed files byte for byte (6 runs).
  • Not run: a full signed and notarized release build (needs the Developer ID secrets).

Across the suite

Matching PRs for every Crafting App, same layout, each with its own figure and colour:

Crafting Apps DMG windows

🤖 Generated with Claude Code

@echelon

echelon commented Oct 8, 2026

Copy link
Copy Markdown
Member

Thank you, the DMG window looks great and the README explaining the layout is really helpful! Two things before we can land it:

  1. Binary size. We try hard not to add large binaries to the repository, because they stay in git history forever. background.tiff is 1.9 MB, mostly paper grain. Could you either drop the grain (flat colours compress to a few tens of KB as an LZW/Deflate TIFF), or generate the TIFF from background.svg at packaging time in package.sh (for example 1x/2x PNGs combined with tiffutil -cathidpicheck on the macOS runner)? The SVG would then be the only committed source.
  2. Asset policy. cargo xtask assets currently fails: packaging/macos/dmg/background.svg and background.tiff need entries in ATTRIBUTION.toml (with kind, licence and sha256, like the other assets), and ATTRIBUTION.md is generated by cargo xtask assets --write rather than edited by hand. See AGENTS.md §1.

Minor: the volume name loses its version so the .DS_Store alias resolves, which is fine; please mention it in the README.

If you haven't already, come join us on Discord: https://discord.gg/artcraft

@XusBadia

XusBadia commented Oct 8, 2026

Copy link
Copy Markdown
Author

Thanks for the review! All three are addressed in the updated branch (now a single commit on top of current main):

  1. Binary size. No bitmap is committed any more, and none is left in the branch history. background.svg (~35 KB) is the only source. Its text is outlined, so it needs no fonts, and the lion is an <image> of the existing assets/app-icon/pdfcraft.svg. package.sh renders it at packaging time with resvg (1x + 2x), joins the two with tiffutil -cathidpicheck, and puts the result in .background/. release.yml installs resvg 0.48.1 on the macOS runner (cargo install resvg --version 0.48.1 --locked). I kept the grain, since it now costs nothing in git. I checked the rendered output pixel by pixel against the earlier TIFF and rebuilt the DMG through the new steps; Finder shows the same window.
  2. Asset policy. background.svg now has its ATTRIBUTION.toml entry (kind = "image", licence, sha256), and ATTRIBUTION.md is regenerated with cargo xtask assets --write. cargo xtask assets passes. DS_Store isn't flagged because it has no asset extension.
  3. Volume name. The README now has a section on it, "The volume name has no version", explaining why and what happens otherwise.

I've applied the same changes to the matching PRs in the other Crafting Apps. And thanks, I'll drop by the Discord!

🤖 Generated with Claude Code

@XusBadia
XusBadia force-pushed the dmg-background branch 2 times, most recently from 19e1110 to c9d83b8 Compare October 8, 2026 15:57
@XusBadia

XusBadia commented Oct 8, 2026

Copy link
Copy Markdown
Author

A quick update: I changed the approach again so the suite stays consistent. VectorCraft's version has just landed (storytold/vectorcraft#493). Its maintainers deliberately kept a committed TIFF there, so that the macOS release job, which holds the signing keychain, doesn't run a build-time cargo install. This PR now matches that:

  • No build-time step. release.yml is back to main, and package.sh only copies files.
  • Small binary. The background here has no paper grain (grain is noise and doesn't compress), so background.tiff (1x + 2x, Deflate, sRGB) is ~230 KB instead of 1.9 MB.
  • generate.py writes the TIFF and dmg-layout.DS_Store from background.svg on any OS. Both are byte-for-byte reproducible and carry nothing from the machine that made them.
  • Assets. ATTRIBUTION.toml has entries for the SVG and the TIFF (with sha256), ATTRIBUTION.md is regenerated with cargo xtask assets --write, and cargo xtask assets passes. The README section on the version-less volume name is still there.

I rebuilt the DMG through the exact package.sh steps and opened it in Finder: background, icons and labels are all in place. If you'd still rather render it at build time, I'm happy to switch it back.

🤖 Generated with Claude Code

The DMG opened as a plain Finder window. It now shows the app icon's figure on
the PdfCraft colour, with PdfCraft.app and the Applications link side by side.
Same approach as PhotoCraft's and VectorCraft's.

- packaging/macos/dmg/: background.svg (source; text outlined, no paper grain,
  the figure an <image> of assets/app-icon), background.tiff (1x + 2x HiDPI,
  16-colour palette, Deflate, sRGB; ~95 KB) and dmg-layout.DS_Store (Finder
  view settings: window, icon size 128, positions, background).
- generate.py writes the TIFF and the layout on any OS, byte-for-byte
  reproducible, with nothing from the machine that ran it.
- package.sh copies them into the staging folder; the image is still built with
  hdiutil makehybrid. Nothing extra runs in the signing job.
- The volume name drops the version: the layout finds the background through
  an alias that includes the volume name. The DMG file name keeps the version.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@XusBadia

XusBadia commented Oct 9, 2026

Copy link
Copy Markdown
Author

@echelon, following what you landed in PhotoCraft (storytold/photocraft#1201), I've applied the same thing here: generate.py now writes a 16-colour palette TIFF with no dithering. The background (already without grain) goes from ~230 KB to 95 KB, with both the 1x and 2x pages, and it's still byte-for-byte reproducible. I updated the ATTRIBUTION.toml sha256 values and the README, regenerated ATTRIBUTION.md, and cargo xtask assets passes. I checked it in Finder, and the lion's engraving holds up fine at 16 colours. If you'd rather render it at package time, as in EffectCraft, just say so.

🤖 Generated with Claude Code

@echelon
echelon merged commit 2f98beb into storytold:main Oct 9, 2026
@echelon

echelon commented Oct 9, 2026

Copy link
Copy Markdown
Member

Merged — thank you @XusBadia! The branded DMG window looks great, and thanks for doing the whole Crafting Apps suite with each app's own icon and colour. (I merged main in to resolve the ATTRIBUTION.md count.)

We'd love to have you in the community Discord if you're not already there: https://discord.gg/artcraft

krichelj pushed a commit to krichelj/pdfcraft that referenced this pull request Oct 11, 2026
macOS DMG: branded window background and icon layout
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