docs(watchos): arm64 vs arm64_32 device builds + App Store publishing

[proggeramlug]

Documents the watchOS targeting and publishing knowledge from the arm64_32 work (#5060) and shipping a real watch-only app.

platforms/watchos.md (corrected + expanded)

The page predated arm64 device support and claimed --target watchos produces arm64_32. Now:

• Architecture matrix — watchos = arm64 (Series 9+/watchOS 26) by default; arm64_32 (Series 4-8/SE) via PERRY_WATCHOS_ARM64_32=1; simulator is arm64-only and can't run arm64_32 binaries.
• Tier-3 device builds — build perry-runtime/perry-ui-watchos from source with nightly -Z build-std + PERRY_RUNTIME_DIR (the old rustup target add arm64_32-apple-watchos only helps the simulator).
• Build env vars — PERRY_WATCHOS_ARM64_32, PERRY_WATCHOS_MIN, PERRY_ENTRY_SYMBOL, plus the rust-objcopy MachOWriter crash on arm64_32 and why we emit the entry symbol directly.
• App rendering modes — default UI-tree shell vs watchos-swift-app / watchos-game-loop.
• Contributor note — 32-bit usize portability rule for perry-runtime (compare pointer guards in u64).

platforms/watchos-app-store.md (new)

Pure tribal knowledge, reverse-engineered from validation errors:

• arm64 required always; arm64_32 required for minOS < 27 → fat binary (wide reach) or arm64-only at minOS 27.
• The arm64-only/minOS-27 builds stall in Processing observation.
• The mandatory iOS-stub wrapper for watch-only apps + required plist keys (WKWatchOnly, ITSWatchOnlyContainer, LSApplicationLaunchProhibited).
• Fat lipo recipe, signing, Transporter upload (altool can't), and devicectl development install (Developer Mode + DDI mount).

Linked under the watchOS entry in SUMMARY.md.

Summary by CodeRabbit

• Documentation
  • Added comprehensive guide for publishing watchOS apps to the App Store, including binary architecture requirements, build steps, configuration details, code signing, and direct installation to watch devices.
  • Enhanced watchOS development documentation with expanded setup instructions for required build tools and workflows.
  • Documented app rendering mode options available for watchOS applications.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR adds comprehensive documentation for publishing watchOS apps to the Apple App Store and expands the existing watchOS development guide. A new guide covers App Store architecture validation, binary building, iOS stub wrapper requirements, signing, and upload procedures. The watchOS guide is enhanced with detailed build setup instructions and documentation of feature-flagged rendering modes.

Changes

watchOS App Store Publishing Documentation

Layer / File(s)	Summary
App Store publishing workflow guide docs/src/platforms/watchos-app-store.md	Complete guide for submitting watchOS-only apps, covering App Store Connect architecture requirements (arm64, arm64_32), fat binary construction with lipo, iOS stub container layout and Info.plist keys, signing with separate provisioning profiles, Transporter-based upload, and development installation via devicectl.
watchOS development setup and rendering modes docs/src/platforms/watchos.md	Requirements section expanded to document Rust target tiering and build-std workflow for perry-runtime dependencies. New "App rendering modes" section describes default SwiftUI renderer, watchos-swift-app feature flag for native apps, and watchos-game-loop for game loops, including TypeScript entry execution and __perry_user_main symbol handling.
Documentation index and cross-references docs/src/SUMMARY.md, docs/src/platforms/watchos.md	SUMMARY.md updated with TOC entry linking to new App Store publishing guide; watchOS guide's Next Steps section extended with "Publishing watchOS apps to the App Store" link.

🎯 2 (Simple) | ⏱️ ~8 minutes

🐰 A watchOS tale unfolds with pride,
App Store paths now open wide,
Build your fat binaries with care,
Sign and stamp with developer flair,
From device to store, your watch app's flight! 📱⌚

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely summarizes the main changes: documenting arm64 vs arm64_32 device builds and App Store publishing for watchOS.
Description check	✅ Passed	The PR description covers all required sections: Summary (changes and rationale), Changes (detailed bullet-point list with file paths), Related issue (n/a), and Testing checklist is mostly addressed via documentation updates.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/apple-watch-targets

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}