Swift SDK + Swift demo clients + Ninja game fixes/perf/UI polish

.github/workflows/swift-procedure-e2e.yml

@@ -0,0 +1,82 @@
+name: Swift Procedure E2E
+
+on:
+  pull_request:
+    paths:
+      - sdks/swift/**
+      - crates/codegen/src/swift.rs
+      - crates/codegen/src/lib.rs
+      - crates/cli/src/subcommands/generate.rs
+      - modules/module-test/**
+      - tools/swift-procedure-e2e.sh
+      - tools/check-swift-demo-bindings.sh
+      - .github/workflows/swift-procedure-e2e.yml
+  push:
+    branches:
+      - master
+    paths:
+      - sdks/swift/**
+      - crates/codegen/src/swift.rs
+      - crates/codegen/src/lib.rs
+      - crates/cli/src/subcommands/generate.rs
+      - modules/module-test/**
+      - tools/swift-procedure-e2e.sh
+      - tools/check-swift-demo-bindings.sh
+      - .github/workflows/swift-procedure-e2e.yml
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || format('sha-{0}', github.sha) }}
+  cancel-in-progress: true
+
+jobs:
+  swift-procedure-e2e:
+    name: Swift Procedure E2E (macOS)
+    runs-on: macos-latest
+    timeout-minutes: 45
+    env:
+      CARGO_TARGET_DIR: ${{ github.workspace }}/target
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dsherret/rust-toolchain-file@v1
+
+      - name: Set default rust toolchain
+        run: rustup default $(rustup show active-toolchain | cut -d' ' -f1)
+
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: ${{ github.workspace }}
+          shared-key: spacetimedb
+          save-if: false
+          prefix-key: v1
+
+      - name: Install SpacetimeDB CLI from local checkout
+        run: |
+          export CARGO_HOME="$HOME/.cargo"
+          echo "$CARGO_HOME/bin" >> "$GITHUB_PATH"
+          cargo install --force --path crates/cli --locked --message-format=short
+          cargo install --force --path crates/standalone --features allow_loopback_http_for_tests --locked --message-format=short
+          ln -sf "$CARGO_HOME/bin/spacetimedb-cli" "$CARGO_HOME/bin/spacetime"
+
+      - name: Show toolchain versions
+        run: |
+          rustc --version
+          cargo --version
+          swiftc --version
+          spacetime --version
+
+      - name: Verify generated Swift demo bindings are in sync
+        run: tools/check-swift-demo-bindings.sh
+
+      - name: Start local SpacetimeDB server
+        run: |
+          spacetime start &
+          disown
+          sleep 5
+
+      - name: Run Swift procedure callback E2E
+        run: tools/swift-procedure-e2e.sh

.github/workflows/swift-sdk.yml

@@ -0,0 +1,114 @@
+name: Swift SDK
+
+on:
+  pull_request:
+    paths:
+      - sdks/swift/**
+      - demo/ninja-game/client-swift/**
+      - demo/simple-module/client-swift/**
+      - tools/swift-procedure-e2e.sh
+      - tools/swift-benchmark-smoke.sh
+      - tools/swift-docc-smoke.sh
+      - .github/workflows/swift-sdk.yml
+  push:
+    branches:
+      - master
+    paths:
+      - sdks/swift/**
+      - demo/ninja-game/client-swift/**
+      - demo/simple-module/client-swift/**
+      - tools/swift-procedure-e2e.sh
+      - tools/swift-benchmark-smoke.sh
+      - tools/swift-docc-smoke.sh
+      - .github/workflows/swift-sdk.yml
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || format('sha-{0}', github.sha) }}
+  cancel-in-progress: true
+
+jobs:
+  swift-sdk:
+    name: Swift SDK (${{ matrix.platform.name }})
+    runs-on: ${{ matrix.platform.runs_on }}
+    timeout-minutes: 45
+    env:
+      SPACETIMEDB_SWIFT_LIVE_TESTS: ${{ vars.SPACETIMEDB_SWIFT_LIVE_TESTS }}
+      SPACETIMEDB_LIVE_TEST_SERVER_URL: ${{ vars.SPACETIMEDB_LIVE_TEST_SERVER_URL }}
+      SPACETIMEDB_LIVE_TEST_DB_NAME: ${{ vars.SPACETIMEDB_LIVE_TEST_DB_NAME }}
+      SPACETIMEDB_LIVE_TEST_TOKEN: ${{ secrets.SPACETIMEDB_LIVE_TEST_TOKEN }}
+    strategy:
+      fail-fast: false
+      matrix:
+        platform:
+          - name: macOS
+            id: macos
+            runs_on: macos-latest
+          - name: iOS Simulator
+            id: ios-simulator
+            runs_on: macos-latest
+
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v4
+
+      - name: Show Swift toolchain version
+        run: swift --version
+
+      - name: Assert legacy Swift SDK path is removed
+        shell: bash
+        run: |
+          if git grep -n "crates/swift-sdk" -- . ':(exclude).github/workflows/swift-sdk.yml'; then
+            echo "Found legacy path references to crates/swift-sdk; expected sdks/swift."
+            exit 1
+          fi
+
+      - name: Test Swift SDK package
+        if: matrix.platform.id == 'macos'
+        run: swift test --package-path sdks/swift
+
+      - name: Validate Swift package lockfile
+        if: matrix.platform.id == 'macos'
+        run: swift package --package-path sdks/swift resolve --force-resolved-versions
+
+      - name: Build simple Swift demo client
+        if: matrix.platform.id == 'macos'
+        run: swift build --package-path demo/simple-module/client-swift
+
+      - name: Build ninja Swift demo client
+        if: matrix.platform.id == 'macos'
+        run: swift build --package-path demo/ninja-game/client-swift
+
+      - name: Run Swift benchmark smoke suite
+        if: matrix.platform.id == 'macos'
+        run: tools/swift-benchmark-smoke.sh
+
+      - name: Run Swift SDK live integration tests (env-gated)
+        if: matrix.platform.id == 'macos' && env.SPACETIMEDB_SWIFT_LIVE_TESTS == '1' && env.SPACETIMEDB_LIVE_TEST_DB_NAME != ''
+        run: swift test --package-path sdks/swift --filter LiveIntegrationTests
+
+      - name: Build Swift SDK target for iOS simulator
+        if: matrix.platform.id == 'ios-simulator'
+        shell: bash
+        run: |
+          IOS_SDK_PATH="$(xcrun --sdk iphonesimulator --show-sdk-path)"
+          swift build \
+            --package-path sdks/swift \
+            --target SpacetimeDB \
+            --triple arm64-apple-ios17.0-simulator \
+            --sdk "$IOS_SDK_PATH"
+
+      - name: Assert visionOS is not targeted yet
+        if: matrix.platform.id == 'macos'
+        shell: bash
+        run: |
+          if rg -q '\.visionOS\(' sdks/swift/Package.swift; then
+            echo "visionOS platform is currently not supported for this SDK."
+            echo "If enabling visionOS, update README/DocC/PUBLISHING docs and CI posture in the same change."
+            exit 1
+          fi
+          echo "visionOS platform not declared in Package.swift (expected posture)."
+
+      - name: Build DocC archive
+        if: matrix.platform.id == 'macos'
+        run: tools/swift-docc-smoke.sh

.gitignore

@@ -264,3 +264,11 @@ nul
 # AI agent config
 .codex
 .claude
+
+# Local PR/planning notes
+changes.md
+swift_sdk_followup_backlog.md
+
+# Swift benchmark local artifacts
+sdks/swift/.benchmarkBaselines/
+sdks/swift/Benchmarks/Baselines/captures/

High Level Goals.md

@@ -0,0 +1,121 @@
+# High Level Goals
+
+## Program Context
+
+We are delivering first-class Swift support for SpacetimeDB inside the monorepo, then upstreaming it as an open-source PR.
+
+Work is happening on branch `swift-integration` and includes:
+
+- Swift runtime SDK (`sdks/swift`)
+- Swift code generation in Rust/CLI (`crates/codegen`, `crates/cli`)
+- End-to-end Swift demos (`demo/simple-module/client-swift`, `demo/ninja-game/client-swift`)
+- CI, tooling, docs, and distribution hardening for Apple app teams
+
+## Updated Product Direction
+
+The goal is a pure Swift, lightweight, high-performance realtime client SDK for Apple development.
+
+Important scope clarification:
+
+- The SDK is rendering-agnostic and does not depend on Metal.
+- Demo rendering is currently SwiftUI/Canvas-based.
+- The key value is low-latency, reactive state replication into native Swift app/game loops.
+
+## End-State Goals
+
+1. Ship a production-credible Swift SDK in the monorepo and upstream PR.
+2. Keep runtime path pure Swift with no third-party runtime dependency burden.
+3. Provide typed Swift bindings from SpacetimeDB schema via official CLI generation.
+4. Prove end-to-end realtime behavior with native Swift demo clients.
+5. Add packaging, documentation, benchmarks, and CI guardrails so Apple teams can trust releases.
+
+## Workstreams
+
+### 1) Swift Runtime SDK
+
+Goal: stable native runtime with robust transport, cache, and API ergonomics.
+
+Target outcomes:
+
+- BSATN encoding/decoding and v2 protocol support
+- websocket transport with reconnect and keepalive handling
+- local replica cache with table delta callbacks
+- reducer/procedure/query APIs (callback + async/await)
+- token persistence and observability hooks
+
+### 2) Swift Code Generation
+
+Goal: avoid hand-written schema glue; generate strongly-typed Swift APIs.
+
+Target outcomes:
+
+- `spacetime generate --lang swift` support in official CLI
+- generated rows/tables/reducers/procedures/module registration
+- binding-drift checks in CI for demo artifacts
+
+### 3) Demo Validation Apps
+
+Goal: prove practical integration and realtime behavior in native Swift clients.
+
+Target outcomes:
+
+- `simple-module` demo validates connect/add/delete/replica updates
+- `ninja-game` demo validates higher-frequency multiplayer state updates and gameplay loops
+- both demos build and stay in sync with generated bindings
+
+### 4) Apple Ecosystem Hardening
+
+Goal: make the package consumable and trustworthy for app teams.
+
+Target outcomes:
+
+- DocC docs/tutorials and publishing guides
+- Apple CI matrix (macOS + iOS simulator; explicit current visionOS posture)
+- package benchmark suite and baseline capture tooling
+- mirror/release automation for package-root SPI/SPM distribution
+
+## Current Status Snapshot
+
+Broadly complete:
+
+- Native Swift runtime package with tests
+- Swift codegen backend and CLI integration
+- Two Swift demo clients in-repo
+- CI coverage for tests/builds/drift/E2E/bench smoke/docs smoke
+- Observability, keepalive/state surface, connectivity-aware reconnect
+- Keychain token utility
+- Benchmark suite + baseline tooling
+- DocC + SPI config + distribution runbooks
+
+Remaining high-priority external step:
+
+- Submit Swift mirror package repository to Swift Package Index and verify docs/platform badges
+
+## PR Success Criteria
+
+1. Branch demonstrates complete Swift SDK path (runtime + codegen + demos + CI).
+2. Validation matrix is green and reproducible.
+3. Documentation reflects actual behavior and support posture.
+4. PR narrative (`changes.md`) is comprehensive and accurate.
+5. Scope claims match implementation (native Swift realtime SDK, not a Metal-specific SDK).
+
+## Principles
+
+- Runtime-first correctness over UI-specific coupling.
+- Pure Swift integration path for Apple developers.
+- Strong typing via generation, not manual schema translation.
+- CI-enforced reproducibility and drift prevention.
+- Clear support posture and release process documentation.
+
+## Near-Term Next Goals
+
+1. Execute manual SPI submission for mirror repo and verify badge endpoints.
+2. Finalize any remaining TODO audit items and reflect them in backlog docs.
+3. Keep Swift parity improvements scoped and test-backed (builder ergonomics, optional helper APIs).
+4. Revisit visionOS support when trigger criteria in `sdks/swift/VISIONOS_ROADMAP.md` are met.
+
+## Non-Goals (Current Phase)
+
+- Building a Metal-specific rendering SDK layer.
+- Coupling SDK internals to any single game/UI framework.
+- Expanding platform support claims beyond documented CI-backed posture.