Zacus Hub — SwiftUI app (macOS + iOS)
Foundation scaffolded 2026-05-24. Three modes: Game-master, Companion, Studio.
See docs/specs/2026-05-24-zacus-hub-app.md.
Generate the Xcode project
brew install xcodegen # one-time
cd apps/zacus-hub
xcodegen generate
open ZacusHub.xcodeproj
XcodeGen reads project.yml and produces a multiplatform .xcodeproj
targeting iOS 17 + macOS 14. ZacusHub.xcodeproj/ is git-ignored —
regenerate after editing project.yml or adding source files in new
directories.
Layout
apps/zacus-hub/
├── project.yml XcodeGen spec
├── Resources/
│ ├── Info.plist shared (iOS leaves macOS keys harmless)
│ └── ZacusHub.entitlements sandbox + network + mic + camera
└── Sources/
├── App/ @main, RootView (tabs/sidebar), Settings
├── Shared/ HubSession, HubAPI (actor), Keychain
├── GameMaster/ operator view (sprint 1+)
├── Companion/ player voice + hints (sprint 3+)
└── Studio/ YAML browser (sprint 5+)
All sources live in one app target — Swift sees them as a single module,
so SourceKit errors before xcodegen generate are expected noise.
Configure at first launch
- Start the gateway (
tools/zacus-gateway/README.md), copy the token. - In the app: gear icon → paste URL (e.g.
http://studio:8400) + token. Saved to Keychain (cc.saillant.zacus.hub). - The Settings sheet shows live auth state (
/v1/auth/ping).
Sprint 0 status
| Surface | State |
|---|---|
| App skeleton (3 modes, settings, auth check) | ✅ scaffolded |
| Gateway connection | ✅ wired |
| Game-master state refresh | ✅ pull (stub data) |
| Companion hint request | ✅ wired to gateway proxy |
| Studio scenario browse | ✅ list + read |
| Push-to-talk, live WS, scenario edit | ⏳ later sprints |
Conventions
- Swift 5.10, strict concurrency on.
- All network calls go through
HubAPIactor — never raw URLSession in views. - View files own no network state — they read from
HubSessionor pass via@Stateafter awaiting an actor call. - French for user-visible strings, English for code/comments.