docs: use PlantUML maps so Kroki fits a phone width

Class diagrams rendered 6556px wide; Gitea clipped that to a black arrowhead and the UML C icon. Stacked maps are 560-780px and render as labelled tables on public Kroki.
docs: restore PlantUML UI maps; draw groups as rectangles
2026-09-14 15:04:22 +00:00 · 2026-09-14 14:56:52 +00:00 · 2026-09-14 14:44:59 +00:00 · 2026-09-14 14:40:28 +00:00 · 2026-09-14 14:25:52 +00:00 · 2026-09-14 14:25:35 +00:00
15 changed files with 644 additions and 101 deletions
@@ -35,7 +35,8 @@ jobs:
      # The job still succeeds quickly so `package`'s `needs:` stays satisfied.
      # Homebrew's xcodegen formula requires Xcode 15.3, which cannot be
      # installed on macOS 12 (#109). The script installs a pinned
-      # prebuilt release instead.
+      # prebuilt release instead. dmgbuild is not installed here — the
+      # test job does not package (#95).
      - name: Ensure host tools
        if: "!(startsWith(github.ref, 'refs/tags/') && contains(github.ref_name, 'prerelease'))"
        run: scripts/ensure-host-tools.sh
@@ -193,8 +194,10 @@ jobs:

      # scripts/package-release.sh runs `xcodegen generate` and dmgbuild;
      # see build-and-test for why brew is not used on macOS 12 (#109).
+      # INSTALL_DMGBUILD isolates dmgbuild in build/.venv-dmgbuild so
+      # the test job never pip-installs it (#95).
      - name: Ensure host tools
-        run: scripts/ensure-host-tools.sh
+        run: INSTALL_DMGBUILD=1 scripts/ensure-host-tools.sh

      - name: Package release
        run: scripts/package-release.sh
@@ -1,45 +1,75 @@
 # ICCery

-Native macOS frontend for printer ICC/ICM profiling. ICCery walks a user from chart generation through measurement, `colprof`, verification, and ColorSync install. It is **not** a colour engine.
+Native macOS frontend for printer ICC/ICM profiling. ICCery walks a user from
+chart generation through measurement, `colprof`, verification, and ColorSync
+install. It is **not** a colour engine.

-All measurement, chart generation, and profile mathematics live in the [Gronod ArgyllCMS 3.5.0 fork](https://git.i3omb.com/gronod/argyllcms), spawned as AGPLv3 child processes. The GUI never `dlopen`s or links Argyll.
+**End-user guide:** the [repository wiki](https://git.i3omb.com/gronod/iccery-v2-mac/wiki)
+covers every screen (Getting Started through Troubleshooting). This README is
+for building, packaging, and contributing.
+
+All measurement, chart generation, and profile mathematics live in the
+[Gronod ArgyllCMS 3.5.0 fork](https://git.i3omb.com/gronod/argyllcms), spawned
+as AGPLv3 child processes. The GUI never `dlopen`s or links Argyll.

 | | |
 |---|---|
 | Product | ICCery v2 for macOS |
 | Bundle | `com.gronod.iccery2` |
+| Version | 2.0.0 |
 | Floor | macOS 12.0 Monterey, universal `arm64` + `x86_64` |
+| Toolchain | Xcode 14.2 / Swift 5.7 (project `SWIFT_VERSION` is 5.0) |
+| CI | Gitea Actions `macos-12` runner |
 | Default branch | `develop` |
-| M6 | Stage 0 calibration, CGATS import, SceneKit gamut viewer, packaging — shipped on `develop` |
-| M7 | Pre-UAT hardening & baseline consolidation — shipped on `develop` |
-| M8 | Deduplication/consolidation contracts & UAT-ready hardening (#79–#86) — shipped on `develop` |
-| M9 | macOS 12 / Xcode 14.2 retarget — shipped on `develop` (PR #145) |
-| M10 | Studio workflow (#146–#149) — in flight on `milestone/m10-studio` |
+| M6 | Stage 0 calibration, CGATS import, SceneKit gamut viewer, packaging — shipped |
+| M7 | Pre-UAT hardening — shipped |
+| M8 | Deduplication contracts & UAT-ready hardening (#79–#86) — shipped |
+| M9 | macOS 12 / Xcode 14.2 retarget (PR #145) — shipped |
+| M10 | Studio workflow: gamut compare (#147), Spot Read (#148), project files (#149) shipped on `develop`; media library (#146) is in the tree, issue still open |
 | Licence | Proprietary source in [`LICENCE.md`](LICENCE.md); bundled Argyll sidecars remain AGPLv3 |

 ## What it does

 The wizard is artefact-gated:

-1. **Stage 0** — printer calibration: `printcal` / `applycal` session, `CAL_` basename restore
-2. **Stage 1** — `targen` → `.ti1`
-3. **Stage 2** — `printtarg` → `.ti2` + TIFF, unmanaged `lp` spool, bound `NSPrintPanel`
-4. **Stage 3** — `instlist` + streaming `chartread` (strip / XY / handheld) → `.ti3`, multi-pass average, CIEDE2000
-5. **Stage 4** — `colprof` → `.icc` / `.icm`; optional `applycal`; `iccgamut` next to the profile
-6. **Stage 5** — `profcheck`, verification history, ColorSync user/system install
+1. **Stage 1** — `targen` → `.ti1`
+2. **Stage 2** — `printtarg` → `.ti2` + TIFF, unmanaged `lp` spool, bound `NSPrintPanel`
+3. **Stage 3** — `instlist` + streaming `chartread` (strip / XY / handheld) → `.ti3`, multi-pass average, CIEDE2000
+4. **Stage 4** — `colprof` → `.icc` / `.icm`; optional `applycal`; `iccgamut` next to the profile
+5. **Stage 5** — `profcheck`, verification history, ColorSync user/system install

-Plus CGATS dataset import (`.ti3` / `.txt` / `.cgats` / `.csv`), SceneKit gamut preview with sRGB overlay, and signed `.dmg` packaging.
+Plus:

-**Not this product:** display calibration (`dispwin` / `dispread`), i18n, Windows/Linux print trees, in-process Argyll, App Sandbox.
+- **Calibrate Printer** — optional `printcal` / `applycal` session under a `CAL_` basename
+- **CGATS import** — `.ti3` / `.txt` / `.cgats` / `.csv`
+- **Media recipes and presets** — printer + paper + ink bound to a preset and optional `.cal`
+- **Spot Read** — live one-patch Lab/XYZ from the instrument
+- **Project files** — `.icceryproj` bookmark over folder, basename, recipe, last ΔE
+- **Gamut viewer** — SceneKit Lab hull, sRGB overlay, second-profile compare, click-inspect
+- **Settings** — default instrument, ΔE good/warning cutoffs, install location, logging
+- Signed `.dmg` packaging with a HiDPI Finder background (Monterey through Sonoma)
+
+**Not this product:** display calibration (`dispwin` / `dispread`), i18n,
+Windows/Linux print trees, in-process Argyll, App Sandbox.

 ## Requirements

- macOS 14+
- Xcode 15.4+ with the macOS 14 SDK and Swift 6.0
- [XcodeGen](https://github.com/yonaskolb/XcodeGen)
- Network once, to fetch Argyll sidecars
+To **run** a packaged build:

-App Sandbox is **off**. Hardened Runtime is **on**. Entitlements live in `ICCery.entitlements`.
+- macOS 12.0 Monterey or later (Intel or Apple silicon)
+
+To **build** on the supported CI/host floor:
+
+- macOS 12 with **Xcode 14.2** (macOS 12 SDK, Swift 5.7)
+- [XcodeGen](https://github.com/yonaskolb/XcodeGen) **2.38.0** (Homebrew’s current
+  formula needs Xcode 15.3; CI installs the pinned zip via
+  `scripts/ensure-host-tools.sh`)
+- Network once, to fetch Argyll sidecars
+- For DMGs: Python 3.9+ and `dmgbuild==1.6.7` in `build/.venv-dmgbuild`
+  (`INSTALL_DMGBUILD=1 scripts/ensure-host-tools.sh`)
+
+App Sandbox is **off**. Hardened Runtime is **on**. Entitlements live in
+`ICCery.entitlements`.

 ## Build

@@ -49,7 +79,7 @@ cd iccery-v2-mac
 git checkout develop

 make fetch-argyll          # Vendor/Argyll/macos-universal/, ad-hoc signed
-make test                  # xcodegen + xcodebuild build test
+make test                  # xcodegen + xcodebuild build test (host arch)
 make universal             # ARCHS='arm64 x86_64' ONLY_ACTIVE_ARCH=NO
 ```

@@ -62,9 +92,14 @@ xcodebuild test -scheme ICCery \
  ARCHS="$(uname -m)"
 ```

-`project.yml` sets `ARCHS: "$(ARCHS_STANDARD)"`, so a plain `xcodebuild test` (and `make test`) builds universal; the `ARCHS="$(uname -m)"` override narrows it to the host slice.
+`project.yml` sets `ARCHS: "$(ARCHS_STANDARD)"`. CI and `make test` override
+that with `ARCHS="$(uname -m)"` so unit/UI tests build the host slice only.
+Fat binaries are `make universal` / `scripts/package-release.sh`.

-Sidecars are **not** in git. `scripts/fetch-argyll.sh` pulls the latest (or `ARGYLL_RELEASE_TAG`) macOS-universal release from `gronod/argyllcms`, extracts to `Vendor/Argyll/macos-universal/`, ad-hoc signs every Mach-O, and fails if `codesign -dvv` or the `instlist` marker is missing.
+Sidecars are **not** in git. `scripts/fetch-argyll.sh` pulls the latest (or
+`ARGYLL_RELEASE_TAG`) macOS-universal release from `gronod/argyllcms`, extracts
+to `Vendor/Argyll/macos-universal/`, ad-hoc signs every Mach-O, and fails if
+`codesign -dvv` or the `instlist` marker is missing.

 ```bash
 # optional
@@ -74,9 +109,11 @@ export ARGYLL_RELEASE_TAG=…    # default: latest
 export GITEA_TOKEN=…           # private releases
 ```

-`make clean` drops `ICCery.xcodeproj`, `DerivedData`, and `Packages/ICCeryCore/.build`.
+`make clean` drops `ICCery.xcodeproj`, `DerivedData`, and
+`Packages/ICCeryCore/.build`.

-Do not open the generated xcodeproj as the source of truth. Edit `project.yml` and regenerate.
+Do not open the generated xcodeproj as the source of truth. Edit `project.yml`
+and regenerate.

 ## Release packaging

@@ -84,11 +121,20 @@ Do not open the generated xcodeproj as the source of truth. Edit `project.yml` a
 scripts/package-release.sh    # fetch → sign → universal build → verify → DMG
 ```

-The script builds with a fixed derived data path (`build/DerivedData`),
-locates `Release/ICCery.app` from it, signs the bundle, recursively verifies
-every bundled Mach-O sidecar (`scripts/verify-sidecar-signatures.sh`), and
-writes `ICCery-${VERSION}-${BUILD_NUM}.dmg` via `dmgbuild`. Sidecars stay
-ad-hoc signed inside the bundle — the app is never `codesign --deep`ed.
+The script builds with a fixed derived data path (`build/DerivedData`), locates
+`Release/ICCery.app` from it, signs the bundle, recursively verifies every
+bundled Mach-O sidecar (`scripts/verify-sidecar-signatures.sh`), builds a
+HiDPI TIFF from `Resources/dmg-background.png` (+ `@2x`) via `tiffutil`, and
+writes `ICCery-${VERSION}-${BUILD_NUM}.dmg` with `dmgbuild==1.6.7`.
+
+Sidecars stay ad-hoc signed inside the bundle — the app is never
+`codesign --deep`ed.
+
+`dmgbuild` is **not** a test-job dependency. The package job sets
+`INSTALL_DMGBUILD=1` so `scripts/ensure-host-tools.sh` creates
+`build/.venv-dmgbuild`. On the Monterey runner (Python 3.9) that install uses
+`PIP_IGNORE_REQUIRES_PYTHON=1` and pins `pip>=24.3,<26.1` (pip 26.1+ needs
+3.10). Missing background art is a hard fail (#95).

 Environment variables read by the pipeline:

@@ -110,30 +156,47 @@ Resources/                 assets; Argyll reference files (not the tools)
 Vendor/Argyll/             fetched sidecars (gitignored)
 Tests/ICCeryCoreTests/     argv goldens, parsers, stores
 Tests/ICCeryUITests/       fixture / mock-binary UI tests
+scripts/ensure-host-tools.sh
 scripts/fetch-argyll.sh
+scripts/package-release.sh
 docs/                      functional spec + v2 ticket plan
 ```

-`ICCeryPrintKit` (issue #16, Quartz / AirPrint / TargetPrint) is v2.1 and is not in this tree.
+`ICCeryPrintKit` (issue #16, Quartz / AirPrint / TargetPrint) is v2.1 and is
+not in this tree.

 ## Architecture

- **Spawn, never link.** Tools resolve through `BinaryResolver` inside the bundle / `Vendor` tree. `$PATH` is not searched. `ARGYLL_NOT_INTERACTIVE=1` is always set.
- **`ProcessManager` actor** owns child lifetime. Streaming tools (`chartread`, `printcal`, etc.) use the event bus; one-shot tools use `runCaptured`. Exclusive `ProcessID` leases. Quit path: `q\n`, ~500 ms, kill; `killAll` on terminate.
- **Argv builders** in ICCeryCore (`TargenArgs`, `PrinttargArgs`, `ChartreadArgs`, `ColprofArgs`, `ApplycalArgs`, `IccgamutArgs`, `ProfcheckArgs`, `LpArgs`, …). UI must not concatenate flags.
- **Atomic artefacts.** Writes go to `*.tmp` then `replaceItemAt`. `applycal` must not replace the input profile on cancel or non-zero exit.
- **Concurrency.** View models are `@MainActor`. No blocking I/O on the main actor. SwiftUI `@Observable` for new state.
- **Print.** Unmanaged `lp` with ColorSync suppression (`AP_ColorMatchingMode` / `AP.ColorMatchingMode`). Captured `NSPrintPanel` options win over derived CUPS keys. Never `lp -o raw`.
+- **Spawn, never link.** Tools resolve through `BinaryResolver` inside the
+  bundle / `Vendor` tree. `$PATH` is not searched. `ARGYLL_NOT_INTERACTIVE=1`
+  is always set.
+- **`ProcessManager` actor** owns child lifetime. Streaming tools
+  (`chartread`, `printtarg`, `colprof`, …) use the event bus; one-shot tools
+  (`printcal`, `applycal`, CUPS) use `runCaptured`. Exclusive `ProcessID`
+  leases. Quit path: `q\n`, ~500 ms, kill; `killAll` on terminate.
+- **Argv builders** in ICCeryCore (`TargenArgs`, `PrinttargArgs`,
+  `ChartreadArgs`, `ColprofArgs`, `ApplycalArgs`, `IccgamutArgs`,
+  `ProfcheckArgs`, `LpArgs`, `SpotReadArgs`, …). UI must not concatenate flags.
+- **Atomic artefacts.** Writes go to `*.tmp` then `replaceItemAt`. `applycal`
+  must not replace the input profile on cancel or non-zero exit.
+- **Concurrency.** View models are `@MainActor`. No blocking I/O on the main
+  actor. Swift 5.7 / macOS 12: `ObservableObject`, not Observation
+  `@Observable`.
+- **Print.** Unmanaged `lp` with ColorSync suppression
+  (`AP_ColorMatchingMode` / `AP.ColorMatchingMode`). Captured `NSPrintPanel`
+  options win over derived CUPS keys. Never `lp -o raw`.
+- **SwiftUI ViewBuilder.** Xcode 14.2 / Swift 5.7 still has the ten-child
+  limit. Split large `VStack`/`Group` trees (#146).

 ## Tests

 ```bash
-# full suite (host arch)
+# full suite (host arch) — same as CI
 xcodebuild test -scheme ICCery \
  -destination 'platform=macOS' \
  ARCHS="$(uname -m)"

-# to compile-check both slices instead:
+# fat compile-check (not the default test path):
 #   ARCHS='arm64 x86_64' ONLY_ACTIVE_ARCH=NO

 # examples
@@ -143,9 +206,20 @@ xcodebuild test -scheme ICCery -destination 'platform=macOS' \
  -only-testing:ICCeryUITests/Milestone5UITests
 ```

-UI tests need an unlocked console (`IOConsoleLocked=false`). Mock Argyll / CUPS fixtures live under the test bundles; they must not be treated as proof that a real `.gam` / `.icc` was extracted.
+CI (`.gitea/workflows/macos.yml`) runs `build-and-test` then `package` on
+`develop` and on `v*` tags. Tags whose name contains `prerelease` skip the
+test job and still package. `pull_request` is wired for **`develop` only**.

-Hardware gates (real instrument, real printer, Gatekeeper-open `.dmg`) are manual and block release, not compile.
+UI tests need an unlocked console (`IOConsoleLocked=false`). Mock Argyll /
+CUPS fixtures live under the test bundles; they must not be treated as proof
+that a real `.gam` / `.icc` was extracted.
+
+Hardware gates (real instrument, real printer, Gatekeeper-open `.dmg`) are
+manual and block release, not compile.
+
+`ArgyllRunnerPrinttargTests.testSuccess` can flake if streaming stdout is
+dropped on a fast mock exit; that is a `ProcessManager` drain race, not a
+missing fixture.

 ## Instruments

@@ -156,11 +230,18 @@ Detected via bundled `instlist`:
 - SpyderPrint (`p3`)
 - SpectroScan (`SS`)
 - DTP20 / 22 / 41 / 51
- XY tables (SpectroScan, i1iO) when the `instlist` name matches `/spectro\s?scan|i1io/i`
+- XY tables (SpectroScan, i1iO) when the `instlist` name matches
+  `/spectro\s?scan|i1io/i`

 ## Docs

-Normative spec is [`docs/`](docs/README.md). Implementation order:
+| Where | Audience |
+|---|---|
+| [Wiki](https://git.i3omb.com/gronod/iccery-v2-mac/wiki) | End users — screens, workflow, troubleshooting |
+| [`docs/`](docs/README.md) | Functional spec (normative for implementers) |
+| [`AGENTS.md`](AGENTS.md), [`BUILD-PLAN.md`](BUILD-PLAN.md) | Agent / branch rules |
+
+Implementation order in `docs/`:

 | Doc | Topic |
 |---|---|
@@ -168,29 +249,40 @@ Normative spec is [`docs/`](docs/README.md). Implementation order:
 | [`docs/03-ipc-and-process-manager.md`](docs/03-ipc-and-process-manager.md) | Spawn / stdin / kill |
 | [`docs/04-argyll-binaries.md`](docs/04-argyll-binaries.md) | CLI argv |
 | [`docs/06-wizard-and-artefacts.md`](docs/06-wizard-and-artefacts.md) | Gating |
+| [`docs/23-assets.md`](docs/23-assets.md) | Icons, DMG chrome |
 | [`docs/24-issues-invariants.md`](docs/24-issues-invariants.md) | Bugs that must not return |
 | [`docs/26-v2-mac-ticket-plan.md`](docs/26-v2-mac-ticket-plan.md) | Gitea tickets |
 | [`docs/PREUAT.md`](docs/PREUAT.md) | Pre-UAT tester kit |

-Agent / branch rules: [`AGENTS.md`](AGENTS.md), [`BUILD-PLAN.md`](BUILD-PLAN.md).
-
 ## Git

 ```
-develop
-  └── milestone/m10-studio   # M10 integration branch
-        └── feat/<issue>-<slug>    # one issue per branch
+develop          # integration; PRs land here unless a milestone branch is announced
+main             # protected release line (PR from develop)
+feat/<issue>-<slug>
+fix/<issue>-<slug>
 ```

-Feature PRs target the current milestone branch, not `develop`. The milestone branch merges to `develop` when its issues are green. Completion PRs for issues #146–#149 target `milestone/m10-studio`; `milestone/m10-studio` merges into `develop` once all milestone gates pass. Do not open umbrella "bugfix" branches that mix tickets.
+Open feature/fix PRs against **`develop`**. A `milestone/m…` integration
+branch is used only while that milestone is assembling; `milestone/m10-studio`
+has been merged and deleted. Do not open umbrella “bugfix” branches that mix
+tickets.
+
+`main` is push-protected and requires status check
+`macOS CI / build-and-test (push)`. Protected **file** patterns on `main`
+block PR merges that touch matching paths — do not set that field to `*`.

 ## Licence

-GUI source: © 2026 Gordon Bolton — see [`LICENCE.md`](LICENCE.md). Viewing and personal evaluation only unless a separate grant says otherwise.
+GUI source: © 2026 Gordon Bolton — see [`LICENCE.md`](LICENCE.md). Viewing
+and personal evaluation only unless a separate grant says otherwise.

-ArgyllCMS binaries fetched into `Vendor/Argyll/` are **AGPLv3**. They stay subprocess-isolated (stdin / stdout / stderr only). Linking them, or spawning via `$PATH`, is a licence break.
+ArgyllCMS binaries fetched into `Vendor/Argyll/` are **AGPLv3**. They stay
+subprocess-isolated (stdin / stdout / stderr only). Linking them, or spawning
+via `$PATH`, is a licence break.

 ## Related

+- [User wiki](https://git.i3omb.com/gronod/iccery-v2-mac/wiki)
 - [gronod/argyllcms](https://git.i3omb.com/gronod/argyllcms) — Argyll 3.5.0 fork (`-u` JSON, `instlist`)
 - [gronod/ICCery](https://git.i3omb.com/gronod/ICCery) — v1 Tauri application (spec source, not this tree)
@@ -220,6 +220,15 @@ struct ManageMediaDialog: View {
            .accessibilityIdentifier("mediaLibraryList")
            .frame(minHeight: 260)

+            if let notice = media.manageApplyNotice {
+                Text(notice)
+                    .font(.callout)
+                    .foregroundStyle(.orange)
+                    .fixedSize(horizontal: false, vertical: true)
+                    .accessibilityIdentifier("manageMediaNotice")
+                    .accessibilityValue(notice)
+            }
+
            HStack {
                Button("Apply selected") {
                    if let id = selection,
@@ -41,6 +41,9 @@ final class MediaLibraryViewModel: ObservableObject {
    @Published var saveMediaApplyCal = false
    /// Inline caption inside the capture sheet (no a11y id — roster complete).
    @Published var saveMediaError: String?
+    /// Last failed Apply while Manage is open. The window banner sits
+    /// behind the sheet on Monterey, so the dialog shows this too (#170).
+    @Published var manageApplyNotice: String?

    /// Pure flow flag — the manage sheet's "Capture current…" asks the
    /// sheet's `onDismiss` to open the capture sheet, avoiding a
@@ -120,24 +123,21 @@ final class MediaLibraryViewModel: ObservableObject {
    /// with warning; the refusal is permanent so re-clicking can't help).
    @discardableResult
    func apply(_ recipe: MediaRecipe) async -> Bool {
+        manageApplyNotice = nil
        guard let r = try? recipe.validated() else {
-            workflow.wizard.showNotice(
-                "Media recipe is invalid — not applied.", kind: .error)
-            return false
+            return failApply("Media recipe is invalid — not applied.", kind: .error)
        }
        guard let preset = environment.presetStore.all()
            .first(where: { $0.id == r.presetID })
        else {
-            workflow.wizard.showNotice(
+            return failApply(
                "Preset \(r.presetID) no longer exists — recipe not applied.",
                kind: .error)
-            return false
        }
        guard preset.colourSpace.lowercased() == r.colourSpace.lowercased() else {
-            workflow.wizard.showNotice(
+            return failApply(
                "Recipe colour space does not match its preset — not applied.",
                kind: .error)
-            return false
        }

        // Existing #82 mapping: presetSelect jumps, Stage 1/2/4 fields.
@@ -145,8 +145,6 @@ final class MediaLibraryViewModel: ObservableObject {
        // Literal per issue: displayName, not the queue id.
        workflow.wizard.printerName = r.printerDisplayName

-        var succeeded = true
-
        // Queue: enumerate fresh via the session's serialized path —
        // listPrinters uses fixed process ids, so an overlapping
        // enumeration would throw duplicateID. An empty result is a
@@ -156,16 +154,14 @@ final class MediaLibraryViewModel: ObservableObject {
                workflow.print.selectedPrinter = r.printerID
                await workflow.print.reloadSelectedCapabilities()
            } else {
-                workflow.wizard.showNotice(
+                return failApply(
                    "Printer \(r.printerDisplayName) is not installed.",
                    kind: .warning)
-                succeeded = false
            }
        } else {
-            workflow.wizard.showNotice(
+            return failApply(
                "Could not enumerate printers — queue left unchanged.",
                kind: .warning)
-            succeeded = false
        }

        // Calibration — the recipe is authoritative and runs after
@@ -195,10 +191,8 @@ final class MediaLibraryViewModel: ObservableObject {
            guard FileManager.default.fileExists(atPath: calPath) else {
                workflow.profile.applyCalibration = false
                workflow.profile.calibrationFile = calPath
-                workflow.wizard.showNotice(
+                return failApply(
                    "Calibration file is missing: \(calPath)", kind: .error)
-                refreshStaleness()
-                return false
            }
            do {
                let staleDays = environment.settingsStore.load().calibrationStaleDays
@@ -215,23 +209,26 @@ final class MediaLibraryViewModel: ObservableObject {
                }
            } catch {
                workflow.profile.applyCalibration = false
-                workflow.wizard.showNotice(
+                return failApply(
                    "Could not load calibration: \(error.localizedDescription)",
                    kind: .error)
-                refreshStaleness()
-                return false
            }
        } else {
            workflow.profile.applyCalibration = false
            workflow.profile.calibrationFile = calPath
        }

-        if succeeded {
-            selectedRecipeID = r.id
-            workflow.wizard.showNotice("Applied \(r.name)")
-        }
+        selectedRecipeID = r.id
+        workflow.wizard.showNotice("Applied \(r.name)")
        refreshStaleness()
-        return succeeded
+        return true
+    }
+
+    private func failApply(_ text: String, kind: Notice.Kind) -> Bool {
+        manageApplyNotice = text
+        workflow.wizard.showNotice(text, kind: kind)
+        refreshStaleness()
+        return false
    }

    // MARK: - Capture
@@ -148,7 +148,9 @@ final class Milestone10MediaLibraryUITests: XCTestCase {
        XCTAssertTrue(apply.waitForExistence(timeout: 10))
        apply.click()

-        let notice = waitFor("noticeText")
+        // The window banner (`noticeText`) sits behind this sheet on
+        // Monterey (#170). Assert the in-sheet copy instead.
+        let notice = waitFor("manageMediaNotice", timeout: 15)
        let text = (notice.value as? String) ?? notice.label
        XCTAssertTrue(
            text.contains("is not installed"),
@@ -25,7 +25,7 @@ Cone-only mark for window/taskbar. Raster set:

 | File | Use |
 |------|-----|
-| `icons/dmg-background.png` (+ `@2x`, `.svg`) | macOS DMG window (ice cream / wordmark scene). Headless `dmgbuild` after #189 |
+| `Resources/dmg-background.png` (+ `@2x`; source `brand/dmg-background.svg`) | macOS DMG window. `scripts/package-release.sh` builds a HiDPI TIFF and passes it to `dmgbuild==1.6.7` from `build/.venv-dmgbuild` (created by `INSTALL_DMGBUILD=1 scripts/ensure-host-tools.sh`). Monterey Python 3.9 needs `PIP_IGNORE_REQUIRES_PYTHON=1` or pip will keep 1.6.5. Missing art is a hard fail (#95, #189). |
 | `icons/wix-banner.bmp`, `wix-dialog.bmp` | MSI |
 | `icons/nsis-header.bmp`, `nsis-sidebar.bmp` | NSIS |

@@ -0,0 +1,89 @@
+@startuml ICCery-UI-sheets
+title Sheets  Settings, presets, media, Spot Read, Gamut, project
+!theme plain
+skinparam backgroundColor white
+skinparam defaultFontColor black
+skinparam defaultFontSize 13
+skinparam mapBackgroundColor white
+skinparam mapBorderColor #222222
+skinparam mapFontColor black
+skinparam arrowColor #222222
+skinparam shadowing false
+hide circle
+top to bottom direction
+
+map "SettingsView.swift" as set {
+  Argyll dir => TextField+Browse : empty = bundled
+  Default instrument => Picker : seeds Stage 3 and Spot Read
+  Enable i1Pro 2 LEDs => Toggle
+  settingsDeltaEGood => TextField
+  settingsDeltaEWarning => TextField : must be greater than Good
+  settingsCalStaleDays => TextField
+  Install location => Picker User or System
+  Ask before overwriting => Toggle
+  Open ColorSync after install => Toggle
+  Log level => Picker
+  Open log folder => Button
+  Cancel / Save => Save stays if validation fails
+}
+
+map "Presets  PresetDialogs.swift" as pre {
+  savePresetName => TextField
+  savePresetDesc => TextField
+  btnCloseSavePresetDialog => Button
+  btnConfirmSavePreset => Button : disabled if name empty
+  presetRow-id => Row : built-in cannot delete
+  btnImportPreset => Button
+  btnExportActivePreset => Button : custom selected
+  btnCloseManagePresetsDialog => Button
+}
+
+map "Media  MediaLibraryDialogs.swift" as media {
+  saveMediaName/Paper/Ink => TextField
+  saveMediaApplyCal => Toggle : disabled if CAL_ or missing file
+  btnConfirmSaveMedia => Button : name+paper+ink required
+  mediaLibraryList => List
+  btnMediaLibraryApply-id => Button per row
+  manageMediaNotice => Caption : failed Apply in-sheet
+  btnMediaLibraryApply => Button : disabled if no selection
+  btnCloseManageMediaDialog => Button
+}
+
+map "spotReadView  SpotReadView.swift" as spot {
+  btnSpotDetectInstruments => Button
+  spotInstrumentSelect => Picker : disabled while running
+  spotSetDefault => Toggle
+  btnSpotStart => Button : needs sidecar, cwd, not chartread
+  btnSpotCalibrate => Button : calibrating
+  btnSpotTrigger => Button : Read, awaitingStrip
+  btnSpotStop => Button : while running
+  btnSpotCopyLab => Button : disabled if no sample
+  btnSpotExportCsv => Button : disabled if no history
+  btnCloseSpotRead => Button Esc : dismiss = Stop
+}
+
+map "gamutView  GamutView.swift" as gam {
+  gamutLayer-srgb => Toggle : can hide, cannot remove
+  gamutLayer-profile => Toggle : disabled if no .gam
+  gamutLayer-compare => Toggle : disabled if no compare
+  btnGamutAddCompare => Menu
+  btnGamutRemoveCompare => Button
+  btnGamutSampleTiff => Button
+  btnResetGamutCamera => Button R
+  gamutLabEntryL/A/B => TextField
+  btnGamutInspectLab => Button
+  btnCloseGamut => Button Esc
+}
+
+map "Project alerts" as proj {
+  projectNewAlert => Alert : New Cancel / Confirm
+  Dirty save => Alert : Save / Don't Save / Cancel
+  projectRelocateSheet => Sheet : cwd missing on Open
+}
+
+set -[hidden]down- pre
+pre -[hidden]down- media
+media -[hidden]down- spot
+spot -[hidden]down- gam
+gam -[hidden]down- proj
+@enduml
@@ -0,0 +1,81 @@
+@startuml ICCery-UI-shell
+title Shell, sidebar, stepper, File menu
+!theme plain
+skinparam backgroundColor white
+skinparam defaultFontColor black
+skinparam defaultFontSize 13
+skinparam mapBackgroundColor white
+skinparam mapBorderColor #222222
+skinparam mapFontColor black
+skinparam arrowColor #222222
+skinparam shadowing false
+hide circle
+top to bottom direction
+
+map "Window" as win {
+  WindowGroup => ICCeryApp.swift : 1280x800 min 1100x700
+  RootView => RootView.swift : hosts every sheet
+  noticeText => NoticeBanner : shown if wizard.notice set; auto-hide 6s
+}
+
+map "Sidebar header" as hdr {
+  openSettingsBtn => Button : always / Settings sheet
+  openAboutBtn => Button : always / About
+  btnToggleAllHelp => Button : toggles yellow help dots
+}
+
+map "Presets" as pre {
+  presetSelect => Picker.menu : none + preset id; none is not factory reset
+  btnSavePresetModal => Button : always
+  btnOpenPresetsDialog => Button : always
+}
+
+map "Media library" as med {
+  mediaSelect => Picker.menu : never reuses presetSelect
+  mediaRecipeStale => Caption : shown if staleReasons nonempty
+  btnMediaLibraryCapture => Button : disabled if no Stage 2 printer
+  btnMediaLibraryManage => Button : always
+}
+
+map "Studio (not stepper)" as stu {
+  btnCalibratePrinter => Button : always; Stage 0
+  btnViewGamut => Button : sidebar always on; same id as Stage 5
+  btnSpotRead => Button : disabled if no cwd or chartread running
+}
+
+map "Stepper 1-5  disk is truth" as stp {
+  Stage1 Generate => always
+  Stage2 Lay out => .ti1
+  Stage3 Measure => .ti1 AND .ti2
+  Stage4 Build => .ti3 (not .ti2 alone)
+  Stage5 Verify => .ti3 AND .icc/.icm
+  Calibrate => not a stepper row; always available
+}
+
+map "Project chip" as chip {
+  projectChipName => Text : bound name or No project
+  projectChipPath => Text : shown if bound
+  projectChipStale => Caption : diskBehindNotes
+  btnProjectReveal => Button : shown if bound
+  btnProjectSave => Button : canSave = bound + basename + cwd
+  btnProjectOpen => Button : shown if not bound
+}
+
+map "File menu" as menu {
+  menuProjectNew => Button Cmd-N
+  menuProjectOpen => Button Cmd-O
+  menuProjectRecents => Menu : disabled if recents empty
+  menuProjectSave => Button Cmd-S : !canSave
+  menuProjectSaveAs => Button Shift-Cmd-S : basename + cwd
+  menuProjectReport => Button : !canReport
+  menuProjectClose => Button : !isBound
+}
+
+win -[hidden]down- hdr
+hdr -[hidden]down- pre
+pre -[hidden]down- med
+med -[hidden]down- stu
+stu -[hidden]down- stp
+stp -[hidden]down- chip
+chip -[hidden]down- menu
+@enduml
@@ -0,0 +1,83 @@
+@startuml ICCery-UI-stage1-2
+title Stages 1-2  Generate Target / Lay Out and Print
+!theme plain
+skinparam backgroundColor white
+skinparam defaultFontColor black
+skinparam defaultFontSize 13
+skinparam mapBackgroundColor white
+skinparam mapBorderColor #222222
+skinparam mapFontColor black
+skinparam arrowColor #222222
+skinparam shadowing false
+hide circle
+top to bottom direction
+
+map "stage-1  Stage1View.swift" as s1 {
+  colourSpace => Picker.segmented : RGB or CMYK
+  patchCountPreset => Picker
+  patchCountCustom => TextField : shown if preset is custom
+  whitePatches => Stepper 0-50
+  blackPatches => Stepper 0-50
+  targetBasename => TextField
+  btnBrowse => Button
+  btnSelectWorkDir => Button
+  btnOpenExisting => Button : .ti1 or .ti2
+  btn-import-dataset => Button : unlocks stage 4
+  selectedPathDisplay => Text
+  targenAdvancedDetails => DisclosureGroup : UI tests pre-expand
+  btnGenerate => Button : needs basename AND directory
+  targenLog => ProcessLogView
+}
+
+map "Stage 1 Advanced (inside disclosure)" as adv {
+  targenGreySteps => Toggle+field : field iff on
+  targenSingleChannelSteps => Toggle+field
+  targenNeutralSteps => Toggle+field
+  targenNeutralConcentration => Toggle+Slider 0-1
+  targenAdaptation => Toggle+Slider 0-1
+  targenPrecondProfile => TextField
+  btnBrowsePrecondProfile => Button
+  targenHighQuality => Toggle
+  targenAlgorithm => Picker
+  targenInkLimitGroup => Toggle+field : CMYK only
+  targenDarkEmphasis => Toggle+Slider 0-3
+  targenDevicePower => Toggle+Slider 0-3
+}
+
+map "stage-2  Stage2View.swift" as s2 {
+  cmWarningBanner => Banner : always on stage 2
+  instrumentSelect => Picker : chart code, not USB port
+  pageSizeSelect => Picker
+  customPageW / customPageH => TextField : pageSize custom
+  tiffDpi => Stepper 72-600
+  printtargLayoutOrder => Picker
+  printtargCustomSeed => TextField : custom seed order
+  btnToggleLabelEdit => Button
+  targetMetadataPrinter => TextField
+  targetMetadataInkSet => TextField
+  targetMetadataDriverPaper => TextField
+  targetMetadataActualPaper => TextField
+  targetLabelPreview => TextField or Text
+  btnCreateLayout => Button : disabled if no basename
+  tiffGallery => Grid : after printtarg
+  btnPrintPage-N => Button : disabled if no printer
+}
+
+map "rawPrintPanel" as prn {
+  printerSelect => Picker CUPS
+  printerStatusBadge => Caption
+  btnRefreshPrinters => Button
+  btnPrinterProperties => Button : disabled if no printer
+  printerTraySelect => Picker : if trays exist
+  printerMediaTypeSelect => Picker : if media types exist
+  btnOrientPortrait => Button
+  btnOrientLandscape => Button
+  btnPrintAll => Button : needs layout AND printer
+  btnAdvanceToStage3 => Button : needs .ti2 unlock
+  printNotificationText => Caption : if printNotice set
+}
+
+s1 -[hidden]down- adv
+adv -[hidden]down- s2
+s2 -[hidden]down- prn
+@enduml
@@ -0,0 +1,84 @@
+@startuml ICCery-UI-stage3-5-cal
+title Stages 3-5 and Calibrate Printer
+!theme plain
+skinparam backgroundColor white
+skinparam defaultFontColor black
+skinparam defaultFontSize 13
+skinparam mapBackgroundColor white
+skinparam mapBorderColor #222222
+skinparam mapFontColor black
+skinparam arrowColor #222222
+skinparam shadowing false
+hide circle
+top to bottom direction
+
+map "stage-3  Stage3View.swift" as s3 {
+  btnDetectInstruments => Button : disabled while detecting
+  chartreadInstrumentSelect => Picker.menu
+  xyTableHint => Caption : if XY instrument
+  xyTablePanel => Place/Align/Scan/Remove
+  chartreadPrompt => Text
+  chartreadLastError => Caption : if notice set
+  btnStartRead => Button : shown if not running; needs basename+cwd
+  btnCalibrate => Button : running and calibrating
+  btnTrigger => Button : running and awaitingStrip
+  btnDoneReadEarly => Button : awaitingStrip
+  btnAccept => Button : place / align / continue / warning
+  btnRetry => Button : error state
+  btnDoneRead => Button : allStripsRead
+  btnCancel => Button : while running
+  swatchGrid => swatch-rowId-loc
+  btnMeasureAnotherSheet => Button : after a finished pass
+  btnFinishAndAverage => Button : finished AND at least one pass
+}
+
+map "stage-4  Stage4View.swift" as s4 {
+  colprofAlgorithm => Picker
+  colprofQuality => Picker
+  colprofFwa => Picker
+  colprofFwaCustomPath => TextField : custom spectrum
+  btnBrowseFwaSp => Button
+  colprofIlluminant => TextField
+  colprofObserver => TextField
+  colprofInputViewCond => TextField
+  colprofOutputViewCond => TextField
+  colprofDescription => TextField
+  colprofCopyright => TextField
+  colprofApplyCalibration => Toggle
+  colprofCalibrationFile => TextField : if applyCalibration
+  btnBrowseCalibrationFile => Button : if applyCalibration
+  btnCreateProfile => Button : basename + cwd, not running
+}
+
+map "stage-5  Stage5View.swift" as s5 {
+  btnVerifyProfile => Button : needs created profile
+  btnViewGamut => Button : disabled if no .gam (same id as sidebar)
+  btnInstallProfile => Button : needs created profile
+  driftPrinterFilter => Picker
+  btnExportHistory => Button
+  btnClearHistory => Button
+  verificationHistoryTable => Table
+  driftChart => not interactive
+  profileOverwriteBtn => Alert : install collision
+  profileRenameBtn => Alert
+  profileCancelCollisionBtn => Alert
+}
+
+map "stage-cal  CalibrationView.swift" as cal {
+  Colour space => Picker.segmented : no a11y id
+  calSteps => TextField
+  White patches => TextField : no a11y id
+  calInkExplore => TextField : CMYK only
+  calNeutralEmphasis => Toggle
+  btnCalGenerate => Button : needs basename + cwd
+  btnCalLayout => Button : same
+  btnCalMeasure => Button : needs .ti3
+  btnCalCompute => Button : .ti3 and not computing
+  calApplyToggle => Toggle : after curves exist
+  btnCalReturn => Button Esc : restores original basename
+}
+
+s3 -[hidden]down- s4
+s4 -[hidden]down- s5
+s5 -[hidden]down- cal
+@enduml
@@ -0,0 +1,12 @@
+# Interactive UI map
+
+PlantUML **maps** (not class diagrams). Class diagrams laid out 6500px wide, so Gitea on a phone showed a sliver of a black arrow and the UML “C” icon.
+
+Each file is one stacked column (~560–780px) that Kroki actually fits in the page.
+
+| Diagram | File | Kroki size |
+| --- | --- | --- |
+| Shell, sidebar, stepper, File menu | [ui-interactive-map-shell.puml](ui-interactive-map-shell.puml) | 563 × 1367 |
+| Stages 1–2 | [ui-interactive-map-stage1-2.puml](ui-interactive-map-stage1-2.puml) | 625 × 1366 |
+| Stages 3–5 + Calibrate | [ui-interactive-map-stage3-5-cal.puml](ui-interactive-map-stage3-5-cal.puml) | 568 × 1386 |
+| Sheets | [ui-interactive-map-sheets.puml](ui-interactive-map-sheets.puml) | 782 × 1502 |
@@ -21,6 +21,8 @@ targets:
          - ICCery.entitlements
          - ICCery.Debug.entitlements
          - Argyll
+          - dmg-background.png
+          - dmg-background@2x.png
      - path: Resources/Argyll
        type: folder
    dependencies:
@@ -1,10 +1,10 @@
 #!/usr/bin/env python3
 # scripts/dmgbuild-settings.py
 #
-# dmgbuild settings for ICCery. Set DMG_APP, DMG_FILENAME and DMG_VOLUME_NAME
-# in the environment, or accept the defaults. Background art can be supplied
-# later by placing a PNG at Resources/dmg-background.png and setting
-# DMG_BACKGROUND.
+# dmgbuild settings for ICCery. scripts/package-release.sh exports
+# DMG_APP, DMG_FILENAME, DMG_VOLUME_NAME, and DMG_BACKGROUND (a
+# HiDPI TIFF). A missing background is a hard error — a grey
+# Finder window is not an acceptable release artefact (#95).

 import os
 import sys
@@ -23,15 +23,23 @@ if not app_path or not app_path.endswith('.app') or not os.path.isdir(app_path):

 files = [app_path]

-# Background art is optional. If the referenced PNG does not exist, fall back
-# to a plain window. See docs/23-assets.md for the DMG background spec.
-background = os.environ.get('DMG_BACKGROUND', 'Resources/dmg-background.png')
-if background and not os.path.exists(background):
-    background = None
+# Finder on Sonoma+ is picky about PNG-with-alpha window pictures and
+# about classic Alias Manager blobs. package-release.sh always passes
+# a flattened HiDPI TIFF as DMG_BACKGROUND. dmgbuild 1.6.7 (bookmark
+# .DS_Store) needs Python >= 3.10, which the Monterey runner does not
+# have; 1.6.5 + TIFF is what CI can ship (#95).
+background = os.environ.get('DMG_BACKGROUND', '')
+if not background or not os.path.isfile(background):
+    sys.stderr.write(
+        'error: DMG_BACKGROUND must point at an existing image '
+        '(got %r)\n' % background)
+    sys.exit(1)

 icon = None

 # Window size is enough for the app icon and the Applications alias.
+# Bitmap is slightly larger than this rect so title-bar chrome on
+# 14+ does not crop the wordmark.
 window_rect = ((100, 100), (660, 400))

 # Use icon view without extra chrome.
@@ -2,19 +2,79 @@
 # scripts/ensure-host-tools.sh
 #
 # Bootstrap host tools needed by CI on the macOS 12 runner:
-#   - xcodegen: pinned prebuilt release from GitHub (Homebrew's current
-#     formula requires Xcode 15.3, which cannot be installed on macOS 12).
-#   - dmgbuild: via pip3 (used by scripts/package-release.sh).
+#   - xcodegen: always. Pinned prebuilt release from GitHub (Homebrew's
+#     current formula requires Xcode 15.3, which cannot be installed on
+#     macOS 12).
+#   - dmgbuild: only when INSTALL_DMGBUILD=1 or --dmgbuild. Isolated in
+#     build/.venv-dmgbuild so the test job never pip-installs it.
 #
-# Safe to run repeatedly: existing tools are left alone.
+# dmgbuild 1.6.6+, ds_store 1.3.2+ and mac_alias 2.2.3 declare
+# Requires-Python >= 3.10. The wheels are py3-none-any and run on the
+# runner's 3.9; PIP_IGNORE_REQUIRES_PYTHON is required or pip will only
+# offer 1.6.5 and keep a cached venv on that version (#95).
+# pip itself is capped at <26.1: 26.1+ needs Python 3.10.
+#
+# Safe to run repeatedly: existing tools are left alone unless the
+# dmgbuild pin is not met.

 set -eu

+ROOT="$(CDPATH='' cd -- "$(dirname -- "$0")/.." && pwd)"
 XCODEGEN_VERSION="2.38.0"
 INSTALL_ROOT="${XCODEGEN_HOME:-$HOME/.local/xcodegen/$XCODEGEN_VERSION}"
+VENV="$ROOT/build/.venv-dmgbuild"
+DMGBUILD_PIN="1.6.7"

-echo "==> Ensuring dmgbuild"
-python3 -c "import dmgbuild" 2>/dev/null || pip3 install dmgbuild
+INSTALL_DMGBUILD="${INSTALL_DMGBUILD:-0}"
+for arg in "$@"; do
+    case "$arg" in
+        --dmgbuild) INSTALL_DMGBUILD=1 ;;
+    esac
+done
+
+if [ "$INSTALL_DMGBUILD" = "1" ]; then
+    echo "==> Ensuring dmgbuild==$DMGBUILD_PIN in $VENV"
+    mkdir -p "$ROOT/build"
+    # pip 26.1+ requires Python 3.10 (dataclass slots). A leftover
+    # `pip install --upgrade pip` on this 3.9 venv installed 26.2.1 and
+    # the next pip invocation crashed. Recreate if pip is already dead.
+    if [ -x "$VENV/bin/python" ] \
+        && ! "$VENV/bin/python" -m pip --version >/dev/null 2>&1; then
+        echo "==> venv pip is broken; recreating $VENV"
+        rm -rf "$VENV"
+    fi
+    if [ ! -x "$VENV/bin/python" ]; then
+        python3 -m venv "$VENV"
+    fi
+    # Without this, pip on Python 3.9 hides 1.6.6+ and leaves 1.6.5.
+    PIP_IGNORE_REQUIRES_PYTHON=1
+    export PIP_IGNORE_REQUIRES_PYTHON
+    "$VENV/bin/python" -m pip install --upgrade 'pip>=24.3,<26.1'
+    "$VENV/bin/python" -m pip install --upgrade --force-reinstall \
+        "dmgbuild==$DMGBUILD_PIN" \
+        'ds_store>=1.3.3' \
+        'mac_alias>=2.2.3'
+    "$VENV/bin/python" -c 'from importlib.metadata import version
+print("dmgbuild", version("dmgbuild"))
+print("ds_store", version("ds_store"))
+print("mac_alias", version("mac_alias"))
+parts=[]
+for p in version("dmgbuild").split("."):
+    try:
+        parts.append(int("".join(c for c in p if c.isdigit()) or "0"))
+    except ValueError:
+        parts.append(0)
+parts += [0, 0, 0]
+raise SystemExit(0 if tuple(parts[:3]) >= (1, 6, 7) else 1)
+'
+    if [ -n "${GITHUB_PATH:-}" ]; then
+        echo "$VENV/bin" >> "$GITHUB_PATH"
+    fi
+    PATH="$VENV/bin:$PATH"
+    export PATH
+else
+    echo "==> Skipping dmgbuild (set INSTALL_DMGBUILD=1 for the package job)"
+fi

 if command -v xcodegen >/dev/null 2>&1; then
    echo "==> xcodegen already on PATH: $(xcodegen --version)"
@@ -103,19 +103,39 @@ EOF
    scripts/verify-sidecar-signatures.sh "$APP"
 fi

-echo "==> Installing / locating dmgbuild"
+echo "==> Locating dmgbuild"
+# The package CI job already ran INSTALL_DMGBUILD=1 ensure-host-tools.sh,
+# which created build/.venv-dmgbuild and prepended it to PATH. Local
+# runs bootstrap the same venv if dmgbuild is missing.
+VENV="$ROOT/build/.venv-dmgbuild"
 if ! command -v dmgbuild >/dev/null 2>&1; then
-    VENV="$ROOT/build/.venv-dmgbuild"
-    if [ ! -d "$VENV/bin" ]; then
-        python3 -m venv "$VENV"
-        "$VENV/bin/pip" install --upgrade pip
-        "$VENV/bin/pip" install dmgbuild
+    if [ ! -x "$VENV/bin/dmgbuild" ]; then
+        INSTALL_DMGBUILD=1 "$ROOT/scripts/ensure-host-tools.sh" --dmgbuild
    fi
    PATH="$VENV/bin:$PATH"
    export PATH
 fi
 if ! command -v dmgbuild >/dev/null 2>&1; then
-    echo "error: dmgbuild not available. Try 'python3 -m venv .venv && pip install dmgbuild'" >&2
+    echo "error: dmgbuild not on PATH; run INSTALL_DMGBUILD=1 scripts/ensure-host-tools.sh" >&2
+    exit 1
+fi
+echo "dmgbuild $(command -v dmgbuild)"
+if [ -x "$VENV/bin/python" ]; then
+    "$VENV/bin/python" -c 'from importlib.metadata import version; print("dmgbuild", version("dmgbuild"))'
+fi
+
+PNG1X="$ROOT/Resources/dmg-background.png"
+PNG2X="$ROOT/Resources/dmg-background@2x.png"
+if [ ! -f "$PNG1X" ] || [ ! -f "$PNG2X" ]; then
+    echo "error: missing $PNG1X or $PNG2X" >&2
+    exit 1
+fi
+mkdir -p "$ROOT/build"
+DMG_BACKGROUND="$ROOT/build/dmg-background.tiff"
+echo "==> Building HiDPI DMG background TIFF"
+tiffutil -cathidpicheck "$PNG1X" "$PNG2X" -out "$DMG_BACKGROUND"
+if [ ! -f "$DMG_BACKGROUND" ]; then
+    echo "error: tiffutil did not write $DMG_BACKGROUND" >&2
    exit 1
 fi

@@ -128,6 +148,7 @@ VOLUME_NAME="ICCery ${VERSION}"
 DMG_APP="$APP" \
 DMG_FILENAME="$DMG" \
 DMG_VOLUME_NAME="$VOLUME_NAME" \
+DMG_BACKGROUND="$DMG_BACKGROUND" \
 dmgbuild -s scripts/dmgbuild-settings.py "$VOLUME_NAME" "$DMG"

 echo "DMG: $PWD/$DMG"
Author	SHA1	Message	Date
gronod	1d056c26bf	docs: use PlantUML maps so Kroki fits a phone width macOS CI / build-and-test (push) Skipped macOS CI / build-and-test (pull_request) Canceled after 0s Details macOS CI / package (pull_request) Canceled after 0s Details Class diagrams rendered 6556px wide; Gitea clipped that to a black arrowhead and the UML C icon. Stacked maps are 560-780px and render as labelled tables on public Kroki.	2026-09-14 15:04:22 +00:00
gronod	c4f037535a	docs: restore PlantUML UI maps; draw groups as rectangles macOS CI / build-and-test (push) Skipped macOS CI / build-and-test (pull_request) Canceled after 0s Details macOS CI / package (pull_request) Canceled after 0s Details Revert the maps to `368ae56` and fix the Kroki render: default package style is a folder, which Gitea scaled to a black tab. Groups are rectangles on a white canvas; shape stereotypes (<<Button>>, <<*.swift>>) are folded into the title so C4/sprites cannot retarget the box.	2026-09-14 14:56:52 +00:00
gronod	191bcb0280	docs: replace hairball graphs with small overviews and tables macOS CI / build-and-test (push) Skipped macOS CI / build-and-test (pull_request) Canceled after 0s Details macOS CI / package (pull_request) Canceled after 0s Details Gitea scaled the 50-node GraphViz maps to unreadably tiny black boxes. Overviews are now ~12 nodes on an opaque white canvas; enable/hide rules live in markdown tables that work in dark mode.	2026-09-14 14:44:59 +00:00
gronod	9c625ee21f	docs: dark-mode GraphViz palette for Gitea Kroki macOS CI / build-and-test (push) Skipped macOS CI / build-and-test (pull_request) Canceled after 0s Details macOS CI / package (pull_request) Canceled after 0s Details Unfilled nodes and default black type sat on a transparent SVG, so dark mode showed only tiny black boxes. Opaque GitHub-dark fills, light labels, larger type.	2026-09-14 14:40:28 +00:00
gronod	40cc4ad701	docs: drop PlantUML UI maps that Kroki 0.30.1 cannot run without AVX2 macOS CI / build-and-test (push) Skipped macOS CI / build-and-test (pull_request) Canceled after 0s Details macOS CI / package (pull_request) Canceled after 0s Details	2026-09-14 14:25:52 +00:00
gronod	658d9813bd	docs: render UI maps with GraphViz for Kroki 0.30.1 macOS CI / build-and-test (push) Skipped macOS CI / package (pull_request) Canceled after 0s Details macOS CI / build-and-test (pull_request) Canceled after 12m40s Details Kroki 0.30.1 PlantUML is a GraalVM native image and requires AVX2. This host has none, so the maps now use GraphViz (dot) — one diagram per file, plus a markdown page with graphviz fences.	2026-09-14 14:25:35 +00:00
gronod	368ae56cf3	docs: split UI PlantUML map into one diagram per file macOS CI / build-and-test (push) Skipped macOS CI / build-and-test (pull_request) Failing after 40m37s Details macOS CI / package (pull_request) Skipped Details Kroki only renders the first @startuml block in a file.	2026-09-14 14:18:07 +00:00
gronod	bd539df009	docs: PlantUML map of every interactive control macOS CI / build-and-test (push) Skipped macOS CI / build-and-test (pull_request) Failing after 3m58s Details macOS CI / package (pull_request) Skipped Details Identifiers, source files, and enable/hide/disable rules for the wizard, sidebar, sheets, and File menu.	2026-09-14 14:03:26 +00:00
gronod	1b91b0a94e	Merge pull request 'fix(ui): media Apply missing-printer notice visible in manage sheet (#170 )' (#171 ) from fix/170-media-library-missing-printer-notice into develop macOS CI / build-and-test (push) Failing after 42m49s Details macOS CI / package (push) Skipped Details fix(ui): media Apply missing-printer notice visible in manage sheet (#170) Fixes #170	2026-09-14 14:37:05 +01:00
gronod	890e7281eb	fix(ui): show media Apply failure inside the manage sheet (#170 ) macOS CI / build-and-test (push) Skipped macOS CI / package (pull_request) Canceled after 0s Details macOS CI / build-and-test (pull_request) Canceled after 2m31s Details Failed Apply kept the sheet open while the window banner sat behind it, so Monterey XCTest never saw noticeText. Mirror the failure string in the dialog (manageMediaNotice) and point the UI test at that identifier. Fixes #170	2026-09-14 13:36:59 +00:00
gronod	ccaad2d940	docs: sync README with Monterey floor, M10, wiki, and packaging macOS CI / package (pull_request) Canceled after 0s Details macOS CI / build-and-test (pull_request) Canceled after 51s Details macOS CI / build-and-test (push) Failing after 43m55s Details macOS CI / package (push) Skipped Details Requirements were still Xcode 15.4 / Swift 6. Point the product at the user wiki, record host-arch tests, the dmgbuild venv, and the current develop-first git workflow.	2026-09-14 12:34:16 +00:00
gronod	7e5e20cb69	Merge origin/main into develop (keep README) macOS CI / package (push) Canceled after 0s Details macOS CI / build-and-test (push) Canceled after 16m10s Details	2026-09-14 13:23:21 +01:00
gronod	e72039c123	Delete README.md	2026-09-14 13:11:43 +01:00
gronod	fa02e774ca	Merge pull request 'fix(packaging): DMG background visible on Sonoma+ (#95 )' (#167 ) from fix/95-dmg-background-sonoma into develop macOS CI / build-and-test (pull_request) Skipped macOS CI / build-and-test (push) Successful in 38m21s Details macOS CI / package (push) Successful in 4m14s Details Reviewed-on: #167	2026-09-14 11:55:39 +01:00
gronod	2a8ad4d5d4	fix(ci): cap pip below 26.1 in the Python 3.9 dmgbuild venv macOS CI / build-and-test (push) Successful in 11s Details macOS CI / package (push) Successful in 4m5s Details macOS CI / package (pull_request) Canceled after 0s Details macOS CI / build-and-test (pull_request) Canceled after 3m29s Details Unbounded pip upgrade installed 26.2.1, which uses dataclass(slots=True) and crashes on Monterey 3.9. Recreate the venv if pip is already broken, then pin pip>=24.3,<26.1 before force-installing dmgbuild 1.6.7.	2026-09-14 10:34:16 +00:00
gronod	c2ac9341c8	fix(ci): force dmgbuild 1.6.7 into the package venv macOS CI / package (pull_request) Canceled after 0s Details macOS CI / build-and-test (pull_request) Canceled after 1m6s Details macOS CI / build-and-test (push) Successful in 11s Details macOS CI / package (push) Failing after 35s Details Python 3.9 hides 1.6.6+ (Requires-Python >=3.10), so dmgbuild>=1.6.5 left a cached 1.6.5 install. The wheels are py3-none-any; install 1.6.7 with PIP_IGNORE_REQUIRES_PYTHON, force-reinstall ds_store>=1.3.3 and mac_alias>=2.2.3, and fail if the venv is still older than 1.6.7.	2026-09-14 10:29:33 +00:00
gronod	1c310706e4	fix(ci): isolate dmgbuild in a venv, skip it on the test job macOS CI / package (pull_request) Canceled after 0s Details macOS CI / build-and-test (pull_request) Canceled after 1m50s Details macOS CI / build-and-test (push) Successful in 13s Details macOS CI / package (push) Successful in 4m12s Details ensure-host-tools.sh always bootstraps xcodegen. dmgbuild now lives in build/.venv-dmgbuild and is only installed when INSTALL_DMGBUILD=1 (package job). The test job no longer pip-installs dmgbuild, which is what failed on Python 3.9. package-release.sh reuses that venv (or bootstraps it locally) instead of creating a second copy.	2026-09-14 10:22:09 +00:00
gronod	7f6c47d85c	fix(ci): do not require dmgbuild 1.6.7 on Monterey Python 3.9 macOS CI / package (pull_request) Canceled after 0s Details macOS CI / build-and-test (pull_request) Canceled after 6m31s Details The tools step runs on the test job. System Python is 3.9; dmgbuild 1.6.6+ declares Requires-Python >=3.10, so pip only lists 1.6.5 and the 1.6.7 floor failed the gate. Install the newest wheel this interpreter accepts. Keep the HiDPI TIFF background path and the hard-fail if art is missing.	2026-09-14 10:14:29 +00:00
gronod	3b6323378e	fix(packaging): DMG background visible on Sonoma+ (#95 ) macOS CI / build-and-test (pull_request) Failing after 20s Details macOS CI / package (pull_request) Skipped Details Pin dmgbuild >= 1.6.7 so Finder gets a bookmark instead of a Monterey-era Alias Manager blob. Feed a HiDPI TIFF from tiffutil rather than the 1x RGBA PNG, and fail the package job if the art is missing instead of shipping a grey window. Exclude installer chrome from the app bundle; it is not an in-app asset.	2026-09-14 09:57:37 +00:00
gronod	d37dcedfd9	Update README.md	2026-09-09 19:18:43 +01:00