fix(macos): bundle native icons with verified legacy fallback

Author: GCWing

.github/workflows/desktop-package.yml

@@ -337,6 +337,19 @@ jobs:
       - name: Download and verify target Flashgrep binary
         run: node scripts/prepare-flashgrep-resource.mjs --target "${{ matrix.platform.target }}"
 
+      - name: Select Xcode for macOS Icon Composer assets
+        if: runner.os == 'macOS'
+        shell: bash
+        run: |
+          test -d /Applications/Xcode_26.2.app/Contents/Developer
+          echo "DEVELOPER_DIR=/Applications/Xcode_26.2.app/Contents/Developer" >> "$GITHUB_ENV"
+
+      - name: Verify native macOS icon bundling
+        if: runner.os == 'macOS'
+        env:
+          OPENBITFUN_TEST_MACOS_BUNDLE: '1'
+        run: node --test scripts/macos-icon-bundle.test.mjs
+
       - name: Build desktop app
         run: ${{ matrix.platform.build_command }}
 

.github/workflows/nightly-artifacts.yml

@@ -219,6 +219,19 @@ jobs:
           CARGO_PROFILE_TEST_DEBUG: "0"
         run: cargo test --locked -p openbitfun-cli --test terminal_process_contracts -- --test-threads=1
 
+      - name: Select Xcode for macOS Icon Composer assets
+        if: runner.os == 'macOS'
+        shell: bash
+        run: |
+          test -d /Applications/Xcode_26.2.app/Contents/Developer
+          echo "DEVELOPER_DIR=/Applications/Xcode_26.2.app/Contents/Developer" >> "$GITHUB_ENV"
+
+      - name: Verify native macOS icon bundling
+        if: runner.os == 'macOS'
+        env:
+          OPENBITFUN_TEST_MACOS_BUNDLE: '1'
+        run: node --test scripts/macos-icon-bundle.test.mjs
+
       - name: Build desktop app
         shell: bash
         run: |

OpenBitFun-Installer/src-tauri/icons/openbitfun-app-icon.icns

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://schema.tauri.app/config/2",
+  "build": {
+    "beforeBundleCommand": "pnpm --dir .. run check:macos-icons"
+  },
+  "bundle": {
+    "icon": [
+      "icons/openbitfun-app-icon.icns",
+      "icons/openbitfun-app-icon.ico",
+      "icons/openbitfun-app-icon.png",
+      "../../assets/brand/macos/openbitfun.icon"
+    ]
+  }
+}

OpenBitFun-Installer/src-tauri/tauri.macos.conf.json

@@ -23,19 +23,90 @@ The iOS App Store icon uses an opaque black square; iOS applies the corner mask.
 mark, a light transparent mark, and the application icon. Fine-line mark exports
 are rendered directly from the SVG with size-specific optical treatments at
 small sizes. Application icons are resized from the preserved application artwork.
-Windows ICO frames, Linux icons, and macOS PNG representations use the matching
-size-specific application exports. Tauri encodes the legacy 16/32 px ICNS
-representations from the same artwork.
+Windows ICO frames and Linux icons use the matching size-specific application
+exports. macOS owns a separate native resource pipeline described below; the
+shared PNGs, Windows ICO, Linux, web, and mobile artwork are unchanged.
+
+## macOS icons
+
+`macos/openbitfun.icon` is the Icon Composer document for macOS 26 and newer,
+including macOS 27. Its background is an opaque, full-bleed black fill and its
+foreground is the transparent silver mark projected from the same brand master.
+It has no baked outer mask, shadow, or Dock padding. macOS applies the enclosure
+and appearance treatment through `Assets.car`. The source uses Icon Composer 1.2
+features supported by Xcode 26.2; it does not require an Xcode 27-only document.
+No language or region-specific icon variants are needed.
+
+The committed ICNS is the static dev and older-macOS fallback. It is rendered
+from that Composer document by Apple's `ictool`, on the separate authored
+`macos/legacy-canvas.json` layout, and encoded with Apple's `iconutil`. That
+legacy layout has an 824 px body on a 1024 px transparent canvas. This is our
+legacy artwork geometry, **not a universal Apple padding requirement**. It never
+alters the modern Composer source. Ten 1x/2x representations cover 16–1024 px.
+There is no runtime OS-version scaling and no modification of ICNS chunks by
+the shared brand generator; canonicalization only orders the native chunks.
+
+Tauri CLI is pinned to **2.11.4** in both workspace apps. The macOS config overlay
+adds `.icon` alongside ICNS; base and Windows/Linux icon selections stay intact.
+Tauri dev reads ICNS through `NSApplication.applicationIconImage`. Bundled builds
+use `CFBundleIconName` with `Assets.car`, plus `CFBundleIconFile` for the legacy
+resource. `tauri.dev.conf.json` and the generated release config inherit the
+platform icon list instead of overwriting it. The minimum application OS version
+is unchanged; compiling the modern catalog for 26 does not raise that minimum.
+
+Normal installs, dev builds, and non-Apple builds use the committed ICNS and need
+no Icon Composer installation. After changing the application mark, Composer
+document, or legacy layout, regenerate on macOS with **Icon Composer 1.2**:
+
+```bash
+# ICON_COMPOSER_APP can point to an alternate location for Icon Composer.app.
+pnpm run generate:macos-icons
+pnpm run generate-brand-assets
+```
+
+The native export manifest records the renderer version and source/output
+hashes. Normal asset generation refuses stale native exports instead of silently
+shipping a mismatched dev icon. Commit the Composer layer, manifest, and all
+three generated ICNS copies together.
+
+Packaging requires **full Xcode 26 or newer**, with `actool` and `assetutil`
+selected by `DEVELOPER_DIR` or `xcode-select`. Command Line Tools alone are not
+enough. Stable/beta and nightly macOS runners select **Xcode 26.2** on both Intel
+and Apple Silicon. The pre-bundle check fails when modern tools are unavailable;
+the build wrapper verifies the resulting catalog, both Info.plist icon keys,
+and the exact fallback bytes before reporting success. No signed bundle is
+modified by verification.
+
+```bash
+node --test scripts/generate-brand-assets.test.mjs scripts/macos-icon-bundle.test.mjs scripts/desktop-tauri-build.test.mjs
+# Full Xcode: exercise actual Tauri + actool packaging in a disposable fixture.
+OPENBITFUN_TEST_MACOS_BUNDLE=1 node --test scripts/macos-icon-bundle.test.mjs
+# Inspect an existing bundle without launching it.
+node scripts/macos-icon-bundle.mjs verify /path/to/OpenBitFun.app
+```
+
+These checks validate resources, native decoding, and package metadata. They do
+not establish visual Dock equivalence on every supported OS or display. Remote
+workspace, remote control, Peer Device Mode, and detached dispatch are not
+exercised by these local packaging checks; their protocols and host logic are
+unchanged.
+
+References: [Apple app icon guidance](https://developer.apple.com/design/human-interface-guidelines/app-icons),
+[Icon Composer](https://developer.apple.com/documentation/xcode/creating-your-app-icon-using-icon-composer),
+[NSApplication.applicationIconImage](https://developer.apple.com/documentation/appkit/nsapplication/applicationiconimage),
+and [Tauri 2.11.4 macOS icon bundler](https://github.com/tauri-apps/tauri/blob/tauri-cli-v2.11.4/crates/tauri-bundler/src/bundle/macos/icon.rs).
 
 Browser entry points select explicit 16/32 px favicons. The system tray reuses
-the configured application/window icon on every desktop platform.
+the macOS template mark on macOS and the configured application icon elsewhere.
 
 Run `pnpm run generate-brand-assets` after changing either source master. The
-generator is the single owner of the derived desktop, web, installer, Android,
-iOS, and HarmonyOS files.
+generator owns the shared desktop, web, installer, Android, iOS, and HarmonyOS
+projections. Native macOS exports have the separate owner described above.
 
-Verify generated dimensions, small-size rim contrast, favicon references, and
-icon containers with `node --test scripts/generate-brand-assets.test.mjs`.
+Verify generated dimensions, small-size rim contrast, favicon references,
+platform selection, and icon containers with
+`node --test scripts/generate-brand-assets.test.mjs`. macOS export and native
+bundling checks also run `scripts/macos-icon-bundle.test.mjs`.
 
 `source/release-letter-mascot.svg` preserves the authored character from
 `openbitfun-letter.html`. Its named body, rigid head/rod, and eye parts are used

assets/brand/README.md

@@ -0,0 +1,6 @@
+{
+  "iconComposerVersion": "1.2",
+  "iconComposerBuild": "76",
+  "sourceSha256": "9b600c6605029a2b23d480ec5595b7634ffb94dd9c6a2cc91a98d645601f65f0",
+  "icnsSha256": "04ca39fd01030f7dcdf787670c3e56f006e33e8384eba14e793db75b6765af3e"
+}

assets/brand/exports/openbitfun-app-icon.icns

@@ -0,0 +1,4 @@
+{
+  "canvasSize": 1024,
+  "artworkBounds": { "x": 100, "y": 100, "width": 824, "height": 824 }
+}

assets/brand/macos/generated.json

@@ -0,0 +1,31 @@
+{
+  "fill": {
+    "solid": "srgb:0.00000,0.00000,0.00000,1.00000"
+  },
+  "groups": [
+    {
+      "name": "Application mark",
+      "layers": [
+        {
+          "image-name": "Mark.png",
+          "name": "Silver mark",
+          "glass": false
+        }
+      ],
+      "shadow": {
+        "kind": "none",
+        "opacity": 0
+      },
+      "specular": false,
+      "translucency": {
+        "enabled": false,
+        "value": 0
+      }
+    }
+  ],
+  "supported-platforms": {
+    "squares": [
+      "macOS"
+    ]
+  }
+}