[macos][release] Add Sparkle update channel for native app

[100yenadmin]

Summary

Add a Sparkle-backed update channel for the native ClawDnD macOS app after the
OpenWorlds shell, native bridge, local .app bundle, and signing identity are
stable.

The goal is to reduce repeated manual rebuild/download cycles for owners and
testers while preserving ClawDnD's state-authority boundary: app updates may
replace the app bundle, but must not mutate campaign state, QA state, private
world seeds, transcripts, or engine-owned game data.

Why this matters

Right now every meaningful app change requires a local rebuild, manual relaunch,
or a fresh artifact handoff. As the OpenWorlds macOS app becomes the primary
play surface, that creates avoidable friction and makes rapid UI/supervisor
iteration more expensive.

Sparkle should become the app update lane once local packaging is stable:

• designers/testers can stay on a known release channel;
• owner machines can pick up app fixes without manual rebuilds;
• rollback and release notes become explicit;
• engine/viewer state remains outside the replaceable app bundle.

Architecture plan

Add Sparkle only after the correction and bridge PRs establish the final app
shape:

1. Bundle identity and signing

   • Decide the stable bundle identifier for ClawDnD.app.
   • Decide dev, nightly, and later beta signing identities.
   • Keep unsigned local dev builds working through ./script/build_and_run.sh --verify.

2. Sparkle integration

   • Add Sparkle to the SwiftPM macOS package or an Xcode packaging layer, based
     on whichever release path the app settles on.
   • Keep Sparkle ownership in the native supervisor layer, not in viewer Python
     or OpenWorlds browser code.
   • Expose a narrow native bridge surface to OpenWorlds Settings:
     • update status;
     • current app version/build;
     • channel;
     • check for updates;
     • last update error;
     • release notes URL when available.

3. Appcast and release channels

   • Define dev/nightly and beta appcast URLs.
   • Document who can publish appcasts and where signing keys live.
   • Do not ship private world seeds, play-state, qa/state, transcripts, or
     local provider config inside the update payload.

4. Rollback and diagnostics

   • Add release notes and rollback notes to the packaging checklist.
   • Include update diagnostics in the OpenWorlds Settings diagnostics export.
   • Make update failures visible without falling back to the old SwiftUI shell.

Acceptance criteria

• ClawDnD.app can check for updates from a configured appcast channel.
• Update status and manual check controls are visible in OpenWorlds Settings.
• Local dev builds still work without Sparkle/appcast configuration.
• The update payload only replaces app-bundle code/assets and never mutates
  campaign/runtime state directories.
• Release documentation explains signing, appcast publishing, rollback, and
  non-notarized/dev-channel constraints.

Validation sketch

From a Lexar-backed checkout:

swift build --package-path macos/ClawDnDApp
./script/build_and_run.sh --verify
codesign --verify --deep --strict dist/ClawDnD.app
plutil -lint dist/ClawDnD.app/Contents/Info.plist
python3 scripts/license_check.py

Manual smoke:

• launch the app;
• open OpenWorlds Settings;
• verify update channel/status is visible;
• run a manual update check against a test appcast;
• confirm campaign state and provider config survive the app update.

Original-agent handoff

Start with:

• macos/ClawDnDApp/Package.swift
• macos/ClawDnDApp/Sources/ClawDnDApp/App/ClawDnDApp.swift
• macos/ClawDnDApp/Sources/ClawDnDApp/Views/RootView.swift
• macos/ClawDnDApp/Sources/ClawDnDApp/Views/WebView.swift
• script/build_and_run.sh
• docs/OPENWORLDS_NATIVE_APP_ROADMAP.md

[coderabbitai]

🔗 Related PRs

#83 - feat(macos): add native ClawDnD app shell [merged]
#101 - feat(macos): surface provider diagnostics [merged]
#103 - feat(macos): add Codex player-facade provider wrapper [merged]
#124 - docs(openworlds): add fidelity and asset contract [merged]
#126 - feat(macos): open OpenWorlds play surface [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[100yenadmin]

Setup guide landed — v1.0.1 (2026-05-28)

docs/SPARKLE_SETUP.md — 7-step integration guide on top of the Developer ID signing committed in v1.0.1 (commit 78645a3):

1. SPM dep
2. SparkleUpdater wrapper
3. Menu item wiring
4. Info.plist (SUFeedURL / SUPublicEDKey / SUEnableAutomaticChecks)
5. EdDSA key pair via generate_keys
6. appcast.xml via generate_appcast
7. Notarization

The Developer ID signing is now the build script's default when the keychain ACL allows it — that's the foundation Sparkle requires. Doc is intentionally separate from the SPM dep add because the bundled XPC services change signing requirements; the actual integration should be a deliberate v1.1.0 "Sparkle-ready" release with all 7 steps landed together rather than added piecemeal mid-1.0.x.