Add architecture guidance for Mac App Store submissions in README_MAS.md

This commit enhances the `README_MAS.md` by providing detailed information on the differences between arm64-only, universal, and x86_64-only app architectures for Mac App Store uploads. It includes recommendations for achieving broad compatibility and clarifies the limitations of submitting multiple builds. This update aims to assist developers in making informed decisions regarding app architecture for their submissions.

build_tools/macos/README_MAS.md

@@ -212,6 +212,51 @@ Outputs:
 
 ---
 
+## Architecture note — arm64 vs universal (arm64+x86_64)
+
+For Mac App Store uploads, your `.pkg` can contain either:
+
+- **arm64-only** app (Apple Silicon only), or
+- **universal** app (arm64 + x86_64), or
+- **x86_64-only** app (runs on Apple Silicon under Rosetta 2, but native Intel only otherwise)
+
+Apple does **not** require universal binaries for review. **arm64-only is allowed**, but:
+
+- Intel Macs **cannot** run an arm64-only app.
+- If you ship arm64-only, App Store Connect will effectively make the app available only to Apple Silicon Macs (and your listing will reflect that).
+
+### Recommendation
+
+- If you want the broadest compatibility, aim for a **universal build**.
+- If you’re okay supporting only Apple Silicon Macs, arm64-only is the simplest path.
+
+### Can I upload two different `.pkg`s (one arm64, one x86_64)?
+
+Not in the way you want.
+
+- In App Store Connect you can upload multiple builds over time, but for any given version/submission you ultimately pick **one build** to submit.
+- Apple will not “merge” two separate uploads (arm64-only + x86_64-only) into one app for customers.
+
+If you want both Apple Silicon and Intel supported **natively**, you need to produce a **single universal** app bundle and package that into **one** `.pkg`.
+
+If you don’t want to deal with universal yet, your practical choices are:
+
+- **arm64-only**: Apple Silicon only.
+- **x86_64-only**: runs on Intel natively, and on Apple Silicon under **Rosetta 2** (slower, but widely compatible).
+
+### Practical reality for this repo
+
+This project depends on large native dependency stacks (Qt, GStreamer, plugins). If you build those via Homebrew, you typically end up with **single-architecture** libraries (arm64 under `/opt/homebrew`, x86_64 under `/usr/local`).
+
+A true universal app requires **all bundled native code** (your executable *and* all `.dylib`/plugins/frameworks you ship) to be universal as well.
+
+If you decide you want universal:
+
+- You’ll need a universal build of **Qt** and **GStreamer** (and all bundled plugins), or
+- Build arm64 and x86_64 bundles separately and combine *matching* binaries where possible (advanced; easy to break signing / plugin loading).
+
+---
+
 ## Troubleshooting — `productbuild` fails with CSSM `-60008` (authorization)
 
 If you see something like:
@@ -303,3 +348,74 @@ xcrun iTMSTransporter -help
 CLI upload requires additional credentials (App Store Connect API key or Apple ID auth) and is easier to get wrong than the Transporter GUI.
 For most folks, **Transporter.app is the recommended path**.
 
+---
+
+## Creating a universal Mac App Store upload using two Macs (arm64 + x86_64)
+
+If you have both an Apple Silicon Mac and an Intel Mac, the most reliable way to ship a universal app for this repo is:
+
+1. Build + deploy the **unsigned** MAS app bundle on each machine (arm64 and x86_64).
+2. Copy both `.app` bundles to the machine that has your signing keys.
+3. Merge them with `lipo` and then **sign + package** once, producing a single universal `.pkg`.
+
+### Step A — Build + deploy (arm64 machine)
+
+On your Apple Silicon Mac:
+
+```bash
+./build_tools/macos/build_app.sh --release --clean --mas --deploy --build-dir ./cmake-build-macos-release-mas-arm64
+```
+
+This produces (unsigned):
+
+- `cmake-build-macos-release-mas-arm64/strawberry.app`
+
+### Step B — Build + deploy (x86_64 machine)
+
+On your Intel Mac:
+
+```bash
+./build_tools/macos/build_app.sh --release --clean --mas --deploy --build-dir ./cmake-build-macos-release-mas-x86_64
+```
+
+This produces (unsigned):
+
+- `cmake-build-macos-release-mas-x86_64/strawberry.app`
+
+### Step C — Copy both app bundles to one “packaging” machine
+
+Pick the Mac that has your **Apple Distribution** and **Installer** identities (private keys) installed.
+Copy both `.app` bundles onto that Mac, for example:
+
+- `/path/to/inputs/strawberry-arm64.app`
+- `/path/to/inputs/strawberry-x86_64.app`
+
+Tip: `rsync` works well for app bundles:
+
+```bash
+rsync -a "/path/to/arm64/strawberry.app" "/path/to/inputs/strawberry-arm64.app"
+rsync -a "/path/to/x86_64/strawberry.app" "/path/to/inputs/strawberry-x86_64.app"
+```
+
+### Step D — Merge + sign + build the universal `.pkg`
+
+On the packaging machine:
+
+```bash
+./build_tools/macos/build_mas_universal_pkg.sh --run \
+  --arm-app "/path/to/inputs/strawberry-arm64.app" \
+  --x86-app "/path/to/inputs/strawberry-x86_64.app" \
+  --codesign-identity "Apple Distribution: Your Name (TEAMID)" \
+  --installer-identity "3rd Party Mac Developer Installer: Your Name (TEAMID)" \
+  --provisionprofile "/path/to/profile.provisionprofile"
+```
+
+Outputs:
+
+- `cmake-build-macos-release-mas-universal/strawberry.app` (universal)
+- `cmake-build-macos-release-mas-universal/strawberry-mas-universal.pkg`
+
+### Important constraints (don’t skip)
+
+- The two input apps must be built from the **same commit** with the **same enabled features** so the app bundle layouts match.
+- Do **not** sign the per-arch apps first; `lipo` invalidates signatures. Sign **only after** merging.